I'm giving some lectures this week about how to _read_ programs, and I've had some things to say about JavaDoc and wondered whether to show some examples of Haddock. I took a certain library that has been mentioned recently in this mailing list. (I shall not identify it. The author deserves praise for his/her contribution, not a public mauling, and the reason for the message is that that package is not unusual.) The reason I chose it was that I thought "actually, >>I<< should learn how to use that, never mind the students." Upon looking at the Haddock web page, - reaction one "this is pretty flashy". - reaction two, "but WHERE IS THE DOCUMENTATION?" What's missing? I've been using Haskell off and on for years now. The package is dauntingly abstract. ("If it wasn't arcane, it wouldn't be UNIX. If it wasn't abstract, it wouldn't be Haskell.") I can see vast drifts of type classes and functional dependencies and so on. What I don't see is "HOW DO I USE THIS STUFF?" Being a bear of very little brain, I need to be told what the big picture is, what the merits of this approach are, links to any papers I should read, and above all, I need some examples of how to use it. It doesn't really matter what "it" is. The package I was looking at is not alone. You people who contribute packages are heroes, and I thank you. But if you could bring your documentation _at least_ up to the standard of say Data.Vector.Generic, that would be wonderful. One of the really nice ideas in the R statistics system is that documentation pages can contain executable examples, and when you wrap up a package for distribution, the system checks that the examples run as advertised. Haskell has a *perfect* fit for this idea in QuickCheck.