Idea to allow people to comment on Haskell docs

[Duncan Coutts]

On Fri, 2006-01-20 at 16:55 -0800, Isaac Jones wrote:

> I think this is quite cool, but there's one thing that concerns me.
> 
> I fear that users will have the sense that these links are being
> monitored by the module authors and that if they make a comment like,
> "there's an error here" or "here's an enhancement" that someone is
> actually going to see it and modify the haddock.  In reality, there's
> no real way to know whether anyone will ever read a comment.  There
> will be far too many pages for anyone to monitor (unless someone is
> going to watch an RSS feed or something).
> 
> This might actually deter people from modifying the haddock code
> directly and submitting patches, since they did their part by
> commenting on the function.
> 
> I'd encourage you to consider how it might interact with the new trac
> ticket system also.  Maybe there should be a "spot a bug" or "make a
> suggestion" link that creates a trac bug.

This is a good point. Let me suggest some possible technical solutions:

It is possible to monitor a number of related wiki pages. Since all the
module pages would be sub-pages of some existing page then by monitoring
the root page for changes in its related pages one could see all changes
in the sub pages. MediaWiki does also have some support for RSS. I've
not looked into that in detail however.

In addition a feature that we might be able to implement for the wiki is
to have all the newly created sub pages of a library's root page contain
some default text rather than starting off blank. That default text
should mention the purpose of the page and where to go instead for
reporting bugs.

If that's too tricky to implement then perhaps one should just go and
pre-create all the wiki pages for each module with the appropriate
initial text. This would not be too much of a chore for most libraries
which only expose a handful of modules. It'd take me a bit longer since
Gtk2Hs has 100+ modules, but it's not intolerable. It can be made
simpler by the use of a MediaWiki template that contains th text. Then
the info can be written once and appear on each page (and if the
template changes the other pages update automatically).

Duncan