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

[Max Rabkin]

On Mon, Oct 10, 2011 at 10:06, Paterson, Ross <R.Paterson at city.ac.uk> wrote:
> Max Rabkin writes:
>> 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.
>
> You may have missed the header on the package page (dark line at the top).

I did indeed. Perhaps it should be bigger? I've just opened up
Synaptic, and it is indeed separate from the description, but there
the synopsis is used as a heading for the description, and it's the
biggest thing on the screen (whereas Hackage uses package name).

> The distinction between synopsis and description is borrowed from the
> Debian package format:
>
> http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions
>
> The two fields are aimed at different audiences.  A Synopsis trying to
> do double duty as the beginning of a general package description won't
> work as well as a stand-alone summary for package lists, etc.

Good point. On the other hand, nobody points package authors to the
Debian documentation (and Debian also has review for newly uploaded
packages, as far as I know).

--Max