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@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