[Haskell-cafe] Package descriptions on hackage

[Joachim Breitner]

Dear hackage package authors,

this is a short message from your distribution package creators: Please,
if possible, write good, not too short descriptions, and also keep them
up to date. Of course, users browsing hackage will benefit as well.

Keep in mind that the users do not know what other packages this relates
to. So if the package is part of a larger set of corresponding packages,
include a general blob and then explain this particular packages. This
is especially true for packages that contain the base types for a suite
of packages.

Also think about all the possible keywords that someone might enter in a
search engine when looking for something like your package, and ideally
explain how your library relates to these keywords so that the user can
estimate whether it useful for him even before reading the API.

Here a few negative examples, not to expose particular authors, but
selected because they were the most resent that the Debian Haskell Team
had packaged.

=========

The http-enumerator package

This package uses attoparsec for parsing the actual contents of the HTTP
connection. The only gotcha is the withHttpEnumerator function,
otherwise should do exactly what you expect. 

(A list of supported features would be great, maybe a short note what
enumerator means. Also, the second sentence is incomprehensible to me
and the latest version does not contain a withHttpEnumerator function
any more)

=========

The representable-functors package

Representable functors 

(Clearly not helpful. Here is what Iulian came up for for the Debian
package, from the individual module documentation, but I still think the
author could do better

This package provides a generalized Store comonad, parameterized by a
Representable functor (the representation of that functor serves as the
index of the store) and a generalized State monad, parameterized by a
Representable functor (the representation of that functor serves as the
state).

Representable functors on Hask all monads, being isomorphic to a reader
monad.

Representable contravariant endofunctors over the category of Haskell
types are isomorphic to (_ -> r) and resemble mappings to a fixed range.

Representable endofunctors over the category of Haskell types are
isomorphic to the reader monad and so inherit a very large number of
properties for free.)

=========

The data-lens package

Haskell 98 Lenses 

(Also not helpful. And probably a very useful package! Iulian wrote „A
lense is a composable notion of a purely functional field accessor.“
which is still quite short, but explains the use of the package much
better)

=========

The algebra package

Constructive abstract algebra 

(Seems to be the “main” package of a series of packages. Yet another
reason for having a good description. Here a suggestion, again by
Iulian:

“This package provides algebraic structures, such as groups, fields,
rings, modules. It also provides bands, also known as idempotent
semigroups (band is a semigroup where every element is equal to its own
square), coalgebras, semirings (rigs), idempotent semirings, also known
as dioids.“)


=========


I know that most people have better things to do than to write API
documentation, so it is not unexpected that, after having written the
API documentation after all, they don’t spend too much time on the
description. But think about it: It is the first thing possible users
are going to see from your package. So if you want to attract users, do
take your time to write a comprehensive and comprehensible description.

Thanks,
Joachim

-- 
Joachim "nomeata" Breitner
  mail at joachim-breitner.de  |  nomeata at debian.org  |  GPG: 0x4743206C
  xmpp: nomeata at joachim-breitner.de | http://www.joachim-breitner.de/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20110905/9a4aeca5/attachment.pgp>