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@joachim-breitner.de | nomeata@debian.org | GPG: 0x4743206C xmpp: nomeata@joachim-breitner.de | http://www.joachim-breitner.de/