Claus Reinke wrote:
Simon, if the less-talented among us (like me) want to contribute to GHC's docs -- and especially documenting the libraries -- what's the best way to go about this? I'm not too comfortable with the notion of just going into GHC's guts and Haddocking the comments, contributing patches willy-nilly because I'd not be certain I did the job right, that I explained things correctly where I had to amplify, etc. Is there some kind of documentation team we poor souls could interact with to assist?
there was the idea of using the wiki for developing documentation improvements, prior to actually submitting the improved texts. the only hint of that scheme i can find right now is:
http://www.haskell.org/haskellwiki/Improving_library_documentation
but establishing a documentation team to help organise the process and to define a realistic workflow (how and where to edit, how and who submits when its "ready", how to avoid extra work due to working in different formats, ..) seems like a good idea. go for it!-)
Of course, the visionary solution would be to wikify the haddocks themselves: imagine to simply point a browser to the documentation and edit it in-place. I think that web-browsers are not ready for that, though: editing things in an extra input box after being redirected to a "edit this page" version just sucks for me, especially for the intended haddock editing. The dream is to have WYSIWYG editing in-place (modulo keyboard/mouse control. Mathematica's front-end comes close to what I have in mind.). Why to learn and adjust wiki markup on a separate page? It's not difficult but it's unnecessary and thus wasted time. Regards, apfelmus