Thanks for this topic and the link; I'm going to try to use it to improve the
docs for hledger and my other projects.
(And I agree, he's wrong about auto-generated docs.)
I seem to remember admiring Parsec's documentation. Though, that reminds me..
A very common problem with online docs is fragmentation. Eg, often to learn haskell libraries the reader has to visit
multiple sites, or multiple locations and formats from one site, and sort through multiple versions of the docs, to
piece together a full picture. You may have the original outdated but most complete docs; the newer, less complete
version hosted on haskell.org; the similar but different version pasted on the haskell wiki with discussion; the
clarifying (or not) blog articles; the api docs on hackage corresponding to your installed software, etc.
To avoid this, I think project leaders need to (a) maintain and clearly identify one canonical starting point for docs
(I favour the hackage page for small projects, a dedicated site or a page on the wiki for larger ones); and (b)
continually seek out, purge and delete out-dated/inconsistent/duplicated docs wherever they be hosted - get them off the
net.
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
