Unhelpful library documentation

[Simon Peyton-Jones]

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