An open letter to the authors of Haskell documentation
When writing Haskell docs, please bear the following points in mind:
- Debug.Trace is not a tracer1. Please stop referring to it as such. In fact, could you please give it a more accurate name, like Debug.Print?
- If tempted to write the words "monadic" or "combinator", write "damn" instead. Your editor will strike it out, and then the sentence will be exactly as it should be.
- By all means, include code examples. In fact, please include more, as they're one of the most helpful forms of documentation. However, please first check that they actually compile. Yes, I'm looking at you, whoever wrote the docs for Control.Monad.State.
[Edit: it seems this is a layout problem. OK, so I should direct my ire at the authors of the error messages and the layout engine. But it would be a Good Thing if the docs pointed this out - you're probably only going to be reading that bit if you're a newbie.]
[Further Edit: I see that totherme has elaborated on this point rather more diplomatically :-) ] - Scientific papers are not an acceptable form of documentation. They're barely an acceptable way of doing science.
- On a similar note, having the bulk of the useful information in documents that are available online but not shipped with the install is damn-all use to those of us trying to hack away from a 'net connection.