Lowering the barrier to entry for people to contribute to library documentation would be a Very Good Thing. There are lots of intelligent and motivated people out there!
Fortunately, we have the Haskell wiki. Magnus's comments look spot-on to me.
| I think the haskell.org wiki would be a good place to document how to
| use APIs. In my opinion the Haddock-generated documents are better kept
| purely as reference documentation with a pointer to the entry-point on
| the wiki for the library in question.
We could encourage every library author to:
* Establish a page on the Haskell Wiki for the library
(http://www.haskell.org/haskellwiki/Library/Data_encoding).
* Set the 'homepage' cabal property to point to that wiki page
(or, if the home page is elsewhere, that home page can point to
the wiki)
* Add a link in the Haddock comments of every module to point to the
same page.
* Make it clear that users are encouraged to write and improve
the wiki documentation
Perhaps such a practice should be explicitly encouraged in the guidelines for submitting a package to Hackage?
Duncan, Don: perhaps these are ideas you could develop for the Haskell Platform?
Simon
| > These are all interesting points, but I found most interesting the
| > conclusion:
| >
| > "Moving forward, I guess one problem is contributing to a library's
| > documentation. There is nothing on the API doc pages that shows you
| > how to do this. I suspect you need to check out the source with darcs
| > (not something I do normally, I just use cabal) and then start email
| > patches or something. Even then, I don't know if I would contribute
| > any documentation -- 'howto' style documentation seems out of place on
| > the API pages, but it is desperately needed."
| >
| > So, what can be done here? Offhand, I want to suggest adding a link to
| > some sort of tutorial module or wiki page. Each page *does* mention
| > that 'Maintainer libraries at haskell.org', but this really isn't
| > helpful; it doesn't tell you where to get the original library source
| > code, how to edit, what libraries@ *is* (anyone with a brain in their
| > head is going to know that libraries@ is some sort of group interface,
| > and is going to refrain from emailing it until they know that they
| > aren't cluelessly spamming/offending potentially hundreds of
| > Haskellers), and so on.
| >
| > Even better would be a link in the Description to the source:
| > 'Control.Concurrent.QSemN is a module in the concurrent package; you
| > can 'darcs get' it from http://foo.... For contributing, please module
| > Contributing/wiki page haskell.org/wiki/Contributing_to_libraries', etc.
| >
| > Thoughts?
|| I think the haskell.org wiki would be a good place to document how to
| use APIs. In my opinion the Haddock-generated documents are better kept
| purely as reference documentation with a pointer to the entry-point on
| the wiki for the library in question.
|| I suppose something similar should be encouraged for libraries on
| Hackage as well. Here's what I'll do with the only library I have on
| there (dataenc):
|| 1. Set the 'homepage' cabal property to point to the wiki page I
| created on the wiki to describe the library
| (http://www.haskell.org/haskellwiki/Library/Data_encoding).
| 2. Add a link in the Haddock comments of every module to point to the
| same page.
|| /M
|| --
| Magnus Therning (OpenPGP: 0xAB4DFBA4)
| magnus＠therning．org Jabber: magnus＠therning．org
|http://therning.org/magnus