On onboarding: Hackage missing documentation

#1

Sometimes I come across packages on hackage whose modules documentation isn’t available, the links are just black.

I know of some ways to finding or building documentation, e.g. using the documentation of the previous version of the package hoping the API is the same, but for beginners it must be very confusing.

An example I just came across is gloss, gloss: Painless 2D vector graphics, animations and simulations.

This package page is probably a roadblock for someone learning Haskell and wanting to use gloss (or any other package in the same situation in hackage). You come across a page with a list of modules but little else. There’s a link to http://gloss.ouroborus.net but that links back to hackage for documentation :slight_smile:

How can we improve the situation?

3 Likes
#2

If I’ve understood this correctly:

https://hackage.haskell.org/upload

…a new Hackage package can be uploaded immediately, without first being a candidate. This could be changed to only promote candidates to regular (permanent) packages once certain criteria have been met e.g. useful documentation - that could help to reduce the number of “under-done” new packages.

As for already-permanent packages…maybe they could be flagged somehow as being “incomplete” or “stale”, with an search option in Hackage to ignore them by default, so they don’t appear in search results.

But there could be a more fundamental problem lurking here - the need for an objective measure of documentation "quality" (whatever that might be!), to avoid yet another opinion-based subjective ranking system…I for one cannot recall encountering such a measure in all my cyber-travels: has anyone else seen one?

#3

Seems like the situation has improved already. gloss’ haddocks are available now: gloss: Painless 2D vector graphics, animations and simulations.

Judging by Build reports for gloss-1.13.2.2 | Hackage, it seems that the docs builder just needed another push?!

In general, I suggest reporting such issues to the package maintainers.

Improved notifications from the Hackage side would be helpful though: Uploaders should be notified when the docs build fails · Issue #989 · haskell/hackage-server · GitHub

2 Likes
#4

It’s a mystery to me why documentation isn’t uploaded by default when uploading to Hackage. It’s very easy to do so, it’s just obscure.

dir=$(mktemp -d dist-docs.XXXXXX)
cabal configure --builddir="$dir"
cabal haddock --builddir="$dir" --haddock-for-hackage --haddock-option=--hyperlinked-source
cabal upload --publish -d $dir/*-docs.tar.gz

If the Cabal tool would simply make this more convenient/well-known and everybody uploaded their own built docs, I think the problem of docs not building on Hackage would be a non-issue.

5 Likes
#5

Interestingly around 24k out of 103k packages listed here have the docs flag set to False so @chris-martin might be onto something.

Also I think it would really help to have some “heartbeat” mechanism to probe for insufficiently documented, already uploaded packages. It could be just creating a new category “documentation quality” to each packages, allowing users to rate packages’ documentation quality directly from Hackage? Unless it requires an account – then it’s probably not going to work.

Alternatively we could traverse the entire list of html documents under each package, at /<package>/docs, ideally re-using haddock’s internals to parse docs and give an appropriate rating (not unlike what this tool does, but for Haddock strings).

1 Like
#6

Nice idea! The answer to the “mystery” is “nobody thought of and proposed it before!” I’ll open a ticket.

2 Likes