[Haskell-cafe] Comments from OCaml Hacker Brian Hurt

[Ian Lynagh]

On Thu, Jan 15, 2009 at 10:39:18PM -0600, Creighton Hogg wrote:
> 
> For you folks who work on GHC, is it acceptable to open tickets for
> poor documentation of modules in base?

Personally, I don't think that doing so would make it more likely that
someone would actually write the documentation; it would just be another
ticket lost in the noise.

The best way to get better docs would be to create a wiki page with
proposed docs, and send a URL to the libraries list and solicit
improvements, in my opinion.

While you may say that people asking for docs for X don't know enough to
write them, I would claim that they normally manage to use X in their
program shortly afterwards, and could thus at least put together a tiny
example of what X can be used for (in English) and how to use it (in
Haskell).

These initial drafts don't have to be perfect, or even correct, as the
libraries list can refine them, but someone does need to put the effort
into picking a good, small example, getting the phrasing nice, etc.

Once the list has settled on good docs, then filing a ticket with the
docs attached is definitely useful.


Thanks
Ian