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

[Max Rabkin]

On Mon, Oct 10, 2011 at 03:17, John Millikin <jmillikin at gmail.com> wrote:
> The package summary is "Type-safe ADT-database mapping library.", which
> gives some idea about what it does.

Whence my suggestion to show this on the package's page. Perhaps I
shouldn't have hidden that at the bottom -- I meant this as my main
point, and I'm afraid I got a little side-tracked.

> In my experience, any package that starts its source files with
>
>     {-# LANGUAGE GADTs, TypeFamilies, ExistentialQuantification,
> StandaloneDeriving, TypeSynonymInstances, MultiParamTypeClasses,
> FunctionalDependencies, FlexibleInstances, FlexibleContexts,
> OverlappingInstances, ScopedTypeVariables, GeneralizedNewtypeDeriving,
> UndecidableInstances, EmptyDataDecls #-}
>
> is probably an experiment in what is possible, rather than a
> production-friendly library.

An experiment that I was interested in, and hoped to find out more
about. But anyway, I see your point.

> Many people upload experimental packages to Hackage so that they can be used
> by other interested people, even though the packages are not ready/intended
> for mass consumption. A lack of documentation in such cases is
> understandable.

Some way of documenting this fact would, however, be helpful.

> I wonder if it would be worth giving package uploaders control over whether
> their packages are shown on the package list? Packages can be manually
> hidden by emailing an admin, but that's a lot of trouble.

In this case I followed an external link, so that would not have
helped me. There is the "stability" field, which has an "experimental"
value, but it's not at all clear what the different values mean other
than "stable".

It is fair that some packages on Hackage are not intended for human
consumption. Perhaps this is caused in part by having our package
installer and humans looking in the same place for information about
Haskell libraries. But I think we can do a better job of
distinguishing these packages. Perhaps a "visibility" or
"release-status" field?

--Max