On Tue, Nov 20, 2007 at 08:55:47AM +0000, Simon Peyton-Jones wrote:
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.
I would advocate using a comment system that is similar to the one at http://djangobook.com/. In terms of user manual comments might be attached to sections and paragraphs in the document. Haddock already generates HTML anchors for every type, variable and class, so these are good candidates to attach user comments to.
* 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.
Comments in both html user guide and library docs could be easily cross-referenced to specific parts of docbook/haskell source. The remaining part (and I admit, labour intensive) would be to take the notes into consideration while updating the documentation for the next release. This doesn't happen too often (once a year? but if I'm wrong please tell me) and I guess the whole point of accepting user's comments is to improve the dock - that is to let writers address the issues in the next version. Now, examples illustrating use of library functions - that's a different story... Regards, -- Krzysztof Kościuszkiewicz Skype: dr.vee, Gadu: 111851, Jabber: kokr@jabberpl.org "Simplicity is the ultimate sophistication" -- Leonardo da Vinci