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...
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
