[Haskell-cafe] On documentation

[Andrew Coppin]

Ivan Miljenovic wrote:
> * When writing the code, it's obvious what it does; as such you may
> think any documentation you may offer is trivial (down the track,
> however...).
>
> * The author is familiar with a library; as such it may not be obvious
> what extra documentation could be needed.

This is the inherant problem with any kind of documentation. (And it's 
by no means limited to Haskell...) The person most qualified to explain 
stuff is the one least qualified to know what needs explaining! ;-)

I would also like to draw attention to something else: Haddock offers 
solid support for writing the "this function does X, that function does 
Y" type of documentation. It has really very weak support for writing 
general overviews, tutorials, examples, etc. Yes, you can put example 
code into the documentation for a specific module. But look at, say, the 
Parsec documentation at

  http://legacy.cs.uu.nl/daan/download/parsec/parsec.html

This tells a new user *far* more than any API listing. And yet, Haddock 
doesn't really support writing this kind of thing properly...