[Haskell-cafe] Synopsis vs Description vs README (was: is it normal for docs to be pending for 24 hours?)

[Herbert Valerio Riedel]

On 2016-11-13 at 18:04:51 +0100, Michael Snoyman wrote:

[...]

> I regularly get complaints of "why don't you do X," where X is a
> significant amount of extra work. Writing up dual descriptions in both
> README.md and cabal description fields is a prime example, and something I
> argued very hard for on Hackage.

> I'm disappointed with the way the description is displayed; I'd have
> much preferred that the README.md files I write would have been used.

Maybe the reasoning behind this wasn't explained well enough, so let me
try again.

The three seemingly overlapping parts

 a) synopsis
 b) description
 c) README

serve three different purposes and have different technical properties
(and you find a very similar 3-part division in e.g. Debian's packaging
and others):

 a) the synopsis is a single-line short title which `cabal list` or
    search results show as a single line; it should give a first rough
    idea what the package is about in order to decide whether you want
    to look closer at b)

 b) this is like a paper abstract, giving you the gist of what a package
    is about, and wether to give it a try; it's displayed by e.g.
    `cabal info somepkg` or at the top of Hackage packages; this should
    contain enough information to know the feature scope of the package
    in order to decide whether to continue looking at c) and/or the
    Haddocks.

    The description field is typically just a few paragraphs, and
    ideally fits on a terminal screen; you don't want it to be too long,
    as it's supposed to be an elevator-pitch for your package.

----

 c) Finally, the README is for additional information which isn't
    suitable for the description-field (like e.g. more in-depth
    explainations, history about package (NB: not the changelog), code
    examples, installation instructions, information about contributing
    etc...); also, since the README is quite easily rather large is
    *not* included in the 01-index.tar

So while there may appear to be some overlap between b) and c), it's
really not that much; and there's precedent for doing it this way.

Also note there's a technical boundary between b) & c) in that a) & b)
are indexed; i.e. by being inside the `.cabal` meta-data, they are
contained in 01-index.tar, and thus are available to external tooling
for text-indexing; Moreover, the synopsis/description fields are part of
the meta-data that gets registered with ghc-pkg, so that information is
available via `ghc-pkg` as well.

Whereas in order to access/search c) you'd currently have to download
the source-tarball (or bypass hackage-security, and access hackage.h.o's
web-services directly but that would come with its own technical
problems by doing so). So READMEs are rather out-of-band information,
and should be treaated as such.

> If you look on resourcet on Hackage, for example, there's a much more
> thorough description of the package at the bottom. I think this was a
> major mistake, but there's not much I can do about it.

Btw, you can modify the current `description` (as well as the
`synopsis`) field via .cabal editing on Hackage if you want to set a
more meaningful description for the benefit of e.g. `cabal info resourcet`
or also Hackage users (since the README is *not* indexed bythe Hackage
search service).