Idea to allow people to comment on Haskell docs

[Duncan Coutts]

All,

People were taking recently about how to make it easier for people to
contribute to the official documentation.

Well here's a suggestion:

We have the Haddock-generated pages link to a wiki. Each module would
link to one page of a wiki. On that wiki page people could add their
extended documentation, notes, example code snippets, pitfalls etc.

The PHP online docs have a similar (albeit more integrated) solution
where each module has user-contributed notes at the end of each page.

For example here's the documentation for the PHP array module:

http://www.php.net/manual/en/ref.array.php

Actually having a wiki might be better than the PHP solution where they
have a series of attributed contributions since with a wiki an 'editor'
can re-arrange the notes to improve the organisation.

The nice thing about most wikis is that if you link to a page that
doesn't yet exist then it can be created. So the wiki does not even need
to be prepared before the docs get pointed at it. The first person to
add notes for a module will just create the corresponding wiki page.

So we'd want to patch haddock to generate the links (controlled by an
extra flag I guess). So I expect that there should be at least a top
level link to the corresponding wiki page.

How about links for each documented entity (eg functions)? That could
generate links with anchors #functionName. If there were no such anchor
then the browser just defaults to the top of the page which is ok.

How would we put the wiki links in for each documented entity?

How about a little [wiki] icon (with a suitable mouse-over descriptive
text) in the right margin of the name.

eg:

rawSystem :: String -> [String] -> IO ExitCode 			[wiki]

        The computation ...

Other suggestions? Just use a top level per-module wiki link?

Duncan