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