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