[Haskell-cafe] Package documentation complaints -- and a suggestion

[Max Rabkin]

Hi all

Following a link from the Yesod book, I arrived at [1], curious to
find out what groundhog was. Once there, I learned... nothing:
"This library provides just the general interface and helper
functions. You must use a specific backend in order to make this
useful."

[1] http://hackage.haskell.org/package/groundhog

Hoping to find more, I clicked on the top-level module. Once again,
the text here was uninformative, though from the example it seems to
be something to do with databases (and it is to be applauded for
including an example in the docs).

So, package authors: PLEASE, tell me what your package does in the
description. Tell me *again* in the top-level haddocks (I may have
come directly there by a link). And then, tell me where to look for
more information. Instead of "This module defines the functions
and datatypes used throughout the framework. Most of them are for
internal use", tell me which are *not* for internal use. Write
documentation for people who don't know how to use your package. Some
people prefer to have this outside of the haddocks (I don't like this
because papers and blogs are less likely to stay up to date than what
is embedded in the file, but for tutorials etc. a website might be
more appropriate) but if so link to it from both the Haddocks and the
package description.

But I also have a concrete suggestion for Hackage: include the package
synopsis on the package's page. The distinction between synopsis and
description can be confusing, and sometimes it seems to violate DRY to
have the same info in both.

To the author of groundhog: I hope you are not offended by my picking
on your package. It's not the only culprit -- just the one that pushed
me over the edge. Of course, I would be pleased if this email
encouraged you to fix it, but I am addressing this rant to the Haskell
community because the problem is a cultural one.

--Max