Unhelpful library documentation

[Duncan Coutts]

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