Unhelpful library documentation

Gwern Branwen gwern0 at gmail.com
Sun Aug 10 15:46:49 EDT 2008

On 2008.08.09 21:33:01 +0100, Magnus Therning <magnus at therning.org> 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?

Goodwin Bunny Blowpipe Montenegro Bechtel SLIP SAAM NSA Ufologico Comverse
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://www.haskell.org/pipermail/libraries/attachments/20080810/8777cc02/attachment-0001.bin

More information about the Libraries mailing list