[Haskell-cafe] re: Improving library documentation

[brad clawsie]

don, i am glad you raised this point, i was going to write a note to
this list soon with a similar request

i would suggest comparing perldoc to haddock and other haskell
documentation tools.

generally speaking, i find that documentation for perl libraries is
written as if the author is enthusiastic about users understanding it.
there are typically detailed function descriptions, and often inlined
examples. on the other hand i have found most haddock documentation to
consist merely of function signatures. as a result i have to employ
spotty supplemental references like the haskell ref at zvon.org (which i
am sure is a copy of a well-known reference set floating around out
there), which includes some examples, or google's code search with
haskell support.

furthermore, perldoc has querying capabilities (-f etc) which preclude
having to surf around references, another great feature.

regardless of format, well-written documentation will go a long way to
forwarding haskell adoption.

brad