proposal for updates in next major HP release

[Simon Michael]

Duncan Coutts wrote:
> 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

Indeed, that's very nice, and I agree with the rest of what you said.

Perhaps related, I am often torn between, and duplicate info across, the various places to put documentation:

- the cabal file, appears on the hackage page
- module or function haddock, appears in the haddock api docs
- the project's web page
- the README file
- non-haddock code comments, visible only to source code readers
- the more elaborate user manual

Currently I prioritise them approximately in the order above, using more of them as the project grows.