On 2008.08.09 21:33:01 +0100, Magnus Therning scribbled 4.2K characters: ...

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.

That seems like one of the best choices to me as well. Thoughts from everyone else? Suggestions about how to actually do it? (Do we add a link to the introduction, hack haddock output in some way to add links at the bottom perhaps, or just use the usual headers - is 'homepage' one of the possible fields?)

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

A useful example; post a link to the Haddock when you do it, would you? -- gwern Goodwin Bunny Blowpipe Montenegro Bechtel SLIP SAAM NSA Ufologico Comverse

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