proposal for updates in next major HP release

[Duncan Coutts]

On Thu, 2009-08-13 at 15:51 -0400, David Menendez wrote:

> It would be nice if the packages in the Haskell Platform met some
> minimum standards for documentation.

Further on this topic...

I think it's a problem with many of our libs that while we have good
enough reference documentation, there is often very little in the form
of introductory documentation. 

As you pointed out in the QC example, each function can be accurately
documented without it giving any idea what some of the concepts mean or
how to use the library.

I think partly this is that haddock is good at and encourages reference
docs but not any other kind. It is possible to put introductory sections
at the top of a module, they have to go in the export list. Without
wanting to blow my own trumpet too much, with the docs for the 'tar'
package I tried to give more introductory explanation and examples of
how to use the api:
http://hackage.haskell.org/packages/archive/tar/0.3.1.0/doc/html/Codec-Archive-Tar.html

Also, I think the synopsis section becomes fairly useless for APIs that
are bigger than about 10 items because it doesn't give any structure or
indicate what is important and what is not. For larger multi-module
packages there's also no obvious place to put introductory text. The
user does not necessarily know which is the "main" module to look for it
in.

Duncan