[Haskell-cafe] Writing great documentation

[Max Rabkin]

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