Unhelpful library documentation

[Gwern Branwen]

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?

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