[Haskell-cafe] Writing great documentation
Haskellers, I have heard many complaints about the average quality on documentation. Therefore, I'd like to encourage you all to read Jacob Kaplan-Moss's series on writing great documentation: http://jacobian.org/writing/great-documentation/. The articles are themselves well-written and contain excellent advice (though I disagree somewhat with the comments on automatically-generated documentation: I find many libraries are excellently haddocumented). Jacob Kaplan-Moss is a developer on the Django project, which is well known for the quality of its documentation. One issue he brings up is having different types of documentation. My impression of many Haskell libraries (my own included) is that, while they may have good reference documentation, they lack tutorials and topic guides. Perhaps we could bring up some examples of Haskell projects with particularly good documentation, as examples to look up to. XMonad has very good overviews and guides for developers, and I like how each user-facing xmonad-contrib module gives a small snippet showing how to use it in ones own config. One area where I think it could be improved (and I plan to do some work on this when I have more free time) is in topical guides on things like how to write your own layout. --Max ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Writing great documentation
On Fri, Nov 13, 2009 at 1:51 PM, Max Rabkin max.rab...@gmail.com wrote: I have heard many complaints about the average quality on documentation. Therefore, I'd like to encourage you all to read Jacob Kaplan-Moss's series on writing great documentation: http://jacobian.org/writing/great-documentation/. The articles are themselves well-written and contain excellent advice (though I disagree somewhat with the comments on automatically-generated documentation: I find many libraries are excellently haddocumented). Jacob Kaplan-Moss is a developer on the Django project, which is well known for the quality of its documentation. Some of the advice is decent, but some (e.g., edit on paper, avoid editing and writing simultaneously) I could never bring myself to do; the ability to continuously revise mid-stream is what keeps me *sane*, and the only reason I can write at all. (It probably helps — or hurts? — that I'm positively neurotic when it comes to grammar and usage.) ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
