Haddock in need of some love and care!

I was browsing https://www.haskell.org/haddock/ and thought that the page could really need some love!

Compared with other parts of haskell.org its looks are very outdated; that not problematic per se, while impressions do matter, I’m very much a fan of MFW, but it does not only look outdated: it is outdated: the last release mentioned (and release notes linked) is 2.15.0 (Aug '14), while on Hackage the most recent one is 2.25.0 (March '21). Note, this is a site of haskell.org, the central and first access point for all things Haskell!

The linked https://haskell-haddock.readthedocs.io/ has the version 2.20.0 documented, which is also not the most current one (2.20.0 was uploaded to Hackage May '18), so the “latest” docs are three years out of date, formally (even if possibly nothing has changed, just maintenance to compile with newer GHCs that makes a very bad impression, as the reader cannot be sure about this).

The whole gives a subjective impression of haddock being in a state of decay (even if it is technically maintained).

Given how important good documentation is, and for any package to get good documentation on hackage it has to go through haddock, I think it would be imperative to give a little more love and care to Haddock, even if it is stable and mostly in maintenance mode.

After all, it’s the library/package authors that evolve our ecosystem and we should make their experience as smooth and easy as possible.

(I was vacillating between “Uncategorized” and “Haskell Foundaton” to post this topic into. Feel free to recategorize if it’s not right here).

9 Likes

As a maintainer of Haddock, I can confirm that we are desperately understaffed and overworked.

10 Likes

Thanks for your efforts, @Kleidukos! I hope the above message did not sound like a criticism of the maintainers, but as a general observation of the state of affairs and a call to action, more along the lines of allocating some more resources.

1 Like

Nope, I didn’t take it as a criticism. :slight_smile:

I find haddock updates are a great way for new and intermediate haskellers to get involved and contribute in a meaningful way. It’s also pretty thankless work! What is the best way for us to get involved and help support your work?

1 Like

The problem I describe is somewhat orthogonal to classic “updates”. Technically we do have updates (0.25.0 was uploaded to Hackage in March 2021, which is reasonably recent for a mature project), but the surrounding care and maintanence (online documentation deployment; landing resp. home page), which of course is busywork, is what is falling behind.

The most sustainable way would be likely to invest into some “devops” work, setting up workflows to automatically generate and deploy new versions of these.

Of course, setting up those workflows is work itself. Unfortunately, I am not proficient with these devopsy methods, so I cannot volunteer. But maybe we have someone in the community or even among the projects which are already under the umbrella of the Foundation who already has similar workflows set up, is fluent in the technologies and for whom the effort would be managable?

I have gotten involved in that sort of thing in the past for haskell.org, and based on those experiences, I would recommend a few things:

  • Identify the specific tasks you want to see completed
  • write them up in github/etc, with clear requirements/etc
  • get buy-in from the admins/owners of the resources
  • then ask people to step up and volunteer their time

Going the other way around is not very resourceful, and a frustrating experience for the person volunteering their time.

4 Likes

Seconded! As someone responsible for merging contributions to haskell.org it’s so much more helpful if contributors make it (seemingly) painfully obvious what a contribution does and why it is needed. Maintainers are very time- and mental energy-limited so the less work you make them to the more likely you are to achieve your desired outcome!

2 Likes