
On Mon, 2008-08-11 at 09:25 +0100, Simon Peyton-Jones wrote:
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?
Hmm. I think the 'homepage' property should point to the package's homepage. For many projects that may well be a wiki site, but bigger projects often have both a homepage and some user-editable wiki. So perhaps it wants another property for wiki links. Further, haddock can link each module or entity to a different uri: --comments-base=URL URL for a comments link on the contents and index pages --comments-module=URL URL for a comments link for each module (using the %{MODULE} var) --comments-entity=URL URL for a comments link for each entity (using the %{FILE}, %{MODULE}, %{NAME}, %{KIND} or %{LINE} vars) We should think about what convention we want there. Eg single page per package with #refs for modules, though bigger packages may want a wiki page per-module with #refs for each entity. This can mostly be encoded into the url itself with var references. The slightly annoying thing is that the urls for the base, module and entity are not necessarily derivable from each other, though in many common cases they are. Perhaps that just needs a convention (like dropping the tail of the url after %{MODULE} to get the base url) eg: wiki: http://www.haskell.org/haskellwiki/Library/Data_encoding/%{MODULE}#%{NAME} gives us: --comments-base=http://www.haskell.org/haskellwiki/Library/Data_encoding/ --comments-module=http://www.haskell.org/haskellwiki/Library/Data_encoding/%{MODULE} --comments-entity=http://www.haskell.org/haskellwiki/Library/Data_encoding/%{MODULE}#%{NAME} That is, not only did we drop "%{NAME}" to get the module one, we also dropped the "#". Another example: wiki: http://wiki.project-foo.org//?module=%{MODULE}#%{NAME} This works less well since we'd get: --comments-base=http://wiki.project-foo.org/?module= --comments-module=http://wiki.project-foo.org/?module=%{MODULE} --comments-entity=http://wiki.project-foo.org/?module=%{MODULE}#%{NAME} but perhaps it's good enough. Duncan