[Haskell-cafe] Package descriptions on hackage

[Neil Mitchell]

There are several problems here:

1) Not everyone can write beautiful clear English descriptions, it
takes a certain skill.
2) The person writing the description is the author, who knows all the
details, but the person reading the description doesn't  - writing for
a different audience is an even harder skill to master.
3) It's easy to miss something when updating a package.
4) Quality documentation places an ongoing maintenance burden on the
package, and while test suites etc. make code maintenance easy, I
don't know any way to automatically check documentation!

Why not email the maintainers of packages you think need a better
description - ideally giving suggestions? I'd welcome that for any of
my packages.

Thanks, Neil

On Mon, Sep 5, 2011 at 11:22 PM, Ivan Lazar Miljenovic
<ivan.miljenovic at gmail.com> wrote:
> On 5 September 2011 23:59, Joachim Breitner <mail at joachim-breitner.de> wrote:
>> 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.
>
> Also for potential users trying to work out what your library does!
>
> Something that I find particularly frustrating is all the libraries of
> the form "hFoo: Haskell bindings to the Foo library"; well, what _is_
> the Foo library?
>
> --
> Ivan Lazar Miljenovic
> Ivan.Miljenovic at gmail.com
> IvanMiljenovic.wordpress.com
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>