[Haskell-cafe] On documentation

[Richard O'Keefe]

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.