Simon Peyton-Jones wrote:
| the php documentation has user contributed notes where people can leave
| sniplets of useful code as comments, eg
|
| http://www.php.net/manual/en/introduction.php
|
| I think this is a very nice feature.
|
| I would love to have this on haskell, especially because the
| documentation often lack example(s)
We've discussed this a couple of times at GHC HQ, at least in relation to GHC's
user manual and library documentation. It's a *great* idea, because it
allows everyone to improve the documentation.
But we're just not sure how to do it:
* What technology to use?
* Matching up the note-adding technology with the existing infrastructure
- GHC's user manual starts as XML and is generated into HTML by DocBook
- In contrast, the library documentation is generated by Haddock.
* Hardest of all: evolution. Both GHC's user manual and library docs
change every release. Even material that doesn't change can get
moved (e.g. section reorganisation). We don't want to simply discard all
user notes! But it's hard to know how to keep them attached; after all
they may no longer even be relevant. They almost certainly don't belong
in the source-code control system.
If someone out there knows solutions to these challenges, and would like
to help implement them, we'd love to hear from you. Accurate documentation,
with rich cross-links (e.g. to source code), and opportunities for the
community to elaborate it, is a real challenge for a language the size of
Haskell and its libraries.
What technology to use, that's the *key* question. If we forget
everything what we currently can do with a computer and instead imagine
what we could do, the answer would probably be:
The documentation / source code can be edited directly while viewing it
(i.e. Wiki + WYSIWYG). Moreover, it's possible to attach lots of
Post-It® notes to sections / paragraphs / sentences with scribbled
comments / questions / remarks about content / administrative tasks.
Those notes can be hidden to get a clean view. A wiki is rather
centralized, so a form of decentralization / version control à la darcs
is needed, at least for some parts like the source code. Last but not
least, there's a tension between quality and editable by everyone, so
some form of access control is mandatory and further means to ensure
quality are needed, that's the hard part.
The above ideal is entirely realizable, just not with existing
technology like web-browsers / text editors . For instance, it's
desirable to be able to edit source / haddock with a text editor like
right now. But one would also like to edit it right in the (generalized)
web-browser. Ideally, one could just pipe the underlying document
through a lens
data Lens s a = Lens { get :: s - a; set :: a - (s - s); }
text:: Lens HaskellDocument ASCII
browser :: Lens HaskellDocument Html
so that the edits in the view are reflected in the document. (Same for
IDEs or GUIs or whatever).
Regards,
apfelmus
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
