2) the Haskell docs _don't_ do good enough a job at giving intuition for what math terms mean
If we fix #2, then #1 is no longer a problem, yes?
For you folks who work on GHC, is it acceptable to open tickets for poor documentation of modules in base? I think leaving the documentation to the tragedy of the commons isn't the best move, but if even a few of us could remember to open tickets when new Haskell'ers complain about something being confusing then it could be on _someone's_ docket.
I can't find the thread at the moment, but this has been discussed before, and my recollection is that wikis were to be used to accumulate documentation comments and updates (there also was some discussion about the best format for comment patches, but getting content was thought to be more important). So, there would be a subset of the Haskell wiki for the base library, and package-specific wiki locations for their documentations. Haddock already seems to provide the necessary support: http://www.haskell.org/haddock/doc/html/invoking.html --comments-base=URL , --comments-module=URL , --comments-entity=URL Include links to pages where readers may comment on the documentation. This feature would typically be used in conjunction with a Wiki system. Use the --comments-base option to add a user comments link in the header bar of the contents and index pages. Use the --comments-module to add a user comments link in the header bar of each module page. Use the --comments-entity option to add a comments link next to the documentation for every value and type in each module. In each case URL is the base URL where the corresponding comments page can be found. For the per-module and per-entity URLs the same substitutions are made as with the --source-module and --source-entity options above. For example, if you want to link the contents page to a wiki page, and every module to subpages, you would say haddock --comments-base=url --comments-module=url/%M So it seems it is only a question of actually using these options with suitably prepared per-package documentation wikis, and improving the documentation or asking for clarifications would be almost as easy as emailing here!-) And if everyone who stumbles over a documentation problem puts the solution on the wiki, documentation should improve quickly (there is still the issue of selecting wiki improvement suggestions for inclusion in the "real" documentation). Does anyone know why these options are not in use already? Claus