Misc package summary page UX observations and requests, for discussion

[jberryman]

The discussion about hackage supporting READMEs in a first-class way, and how the presentation should work (see #279 and especially #356 , and here, FWIW, is an experimental fork that someone made exploring a page re-design (I don't think it addresses my issues)) got me thinking about my user experience with hackage package summary pages (e.g. https://hackage.haskell.org/package/lens).

I wanted to open this issue to talk about how I use hackage, to present a couple ideas and open a discussion about them (and other ideas people have, based on their own use of hackage). If there is interest and a fruitful discussion, this issue can be closed and maybe individually feature requests could be opened for things there is consensus around.

Here's the way I use hackage, as best I can figure out:

Things I do (nearly) every time I go to a package's "Contents" page

• Make sure I'm at the package's latest version
• Click through to a specific module (maybe going back and clicking through to a different one, etc.)
• Look at dependencies, maybe clicking through

Things I occasionally do (maybe 15-20% of the time):

• Look at upload date
• Click through to package's github page
• Look at package author (remind myself who wrote it, whether they're also the author of another dependency I'm concerned with; this narrowly makes it out of the section below)

Things I do perhaps only once, for new packages (maybe 5% of the time)

• Read package description
• Look at number of downloads to get an idea of popularity

So with that said...

Some ideas that might improve my user experience

Sorted from most to least important to me

1. A prominent "Latest" button, perhaps in the form of a clickable banner if not on the latest version

2. Try to keep the following above the fold, prioritizing in order: the link to latest version (and the version number), the clickable module hierarchy, the dependencies list, the package's homepage link (well I really in all cases only care about the link to the github page, but these are often the same), and (less prominently) the number of downloads in the last 30 days. This means...

   2a. Push the package description below the 5 sections mentioned above. (there could be a link to the description below, above the fold)

3. Keep the upload date and version number side-by-side (e.g. I see an issue on github and I know the date it was closed, and now I'm wondering if this package has the fix).

   3a. Present this as just the month, day, and year, unless the package was released today, in which case you can include the time as well

Thoughts on these and other ideas? It might be helpful to specify whether you agree with how I've layed out priorities of page elements above, or how you would prioritize elements differently, and/or where your suggestion would fit into the framework I sketched out above.

[stepcut]

Regarding the 'Latest' button -- you might check out the chrome plugin, hackage-fu which does just that. It would be nice to make those features native.

[bitemyapp]

@stepcut hackage-fu breaks for me here and there, so it'd be better if it was just native. I've considered adding this to Hackage but the way documentation is handled and rendered means you're effectively mutating a foreign document. This also means Hackage can no longer blindly reserve whatever Haddocks were uploaded and now must necessarily care what Haddock does with its HTML. Not good.

It would be better if more emphasis was placed on the Haddock API to extract, cache, and then reinject documentation into a wrapping template rather than directly serving from the tarball.

[gbaz]

I suspect the "latest" button could be more safely injected post-hoc with browser-side javascript? Of course that means "mutating" the already generated html as well, but in this case just with a <script> tag, so less fragile...

[bgamari]

@bitemyapp, I think you and @stepcut are actually in agreement regarding it being nice to make those features native.

@jberryman, thanks for writing these thoughts down. I think it's true that documentation access is the single largest use of Hackage in terms of raw hits. I may be the minority here but I also find the source-repository data to be quite useful (e.g. when submitting drive-by version bound bumps).

I agree that more often than not I simply want to see the latest release. However, an important 5% of the time I want to look back to a particular previous version (e.g. to see when a definition was introduced). At the moment this task is unnecessarily hard due to the difficulty of visually parsing the version list. There would be bonus points if Haddock were modified such that one could jump between versions of a given module without ever leaving the module's page.

I would also say that I quite like current minimalist visual styling of Hackage. The Scaladoc variant and dark blue themes referenced in @dzackgarza's issue in my opinion regress in both legibility and aesthetics. This may just be me, however.

[NathanHowell]

@bitemyapp how about having haddock generate json/xml/etc then use separate app to render these to hackage's style? This is the approach taken by C#. Baking support for a bunch of different file formats into haddock seems clumsy.

[gbaz]

Actually we have a gsoc project that seems tied to the idea of generating and saving the intermediate haddock information and not just the html output. It also helps in figuring out changes related to semantic versioning, etc. So I agree that long-term the idea of either using the existing format, or creating a slightly different, but still machine-readable, one, is important. In the meantime, I don't think we need to go that far just for a "Latest" button :-)

[bitemyapp]

@NathanHowell Having a well-maintained API and data structure that encapsulates everything you'd want from the haddocks themselves is necessary to have JSON/XML/whatever and is all Hackage should want anyway. I'm not sure why you'd have two Haskell libraries talking to each other via XML.

If Haddock already has what's needed there (I suspect there's at least a few things missing, last I looked there was one very sad and lonely module sitting by itself in the corner), then the onus would be on Hackage to take advantage of it if people think this is a good idea. I'm not sure why a serialized intermediate representation is needed for Hackage to fix things here, you're pushing the source dist to Hackage anyway.

[NathanHowell]

@bitemyapp to allow rendering docs for packages that no longer build with current GHC. Hackage has (had?) a load of different doc formats, depending on the version of GHC and haddock in use at the time.

[NathanHowell]

@bitemyapp one more comment (even though this is getting offtopic): why not have the machine readable haddocks uploaded in the sdist? since the client (presumably) has all the dependencies and native libraries required to build the package the client should generate the docs too.

[Rufflewind]

Some more suggestions:

• Regarding dates, I think it would be more readable to have it in ISO format: 2015-05-29 13:23:15 UTC. This way the most important part comes first ("last updated in 2002?? never mind then"). I don't think there is a use in seeing the day of the week in particular.

  It would be useful if the date were moved up to be close to Versions, since they are related information.

• As for the priority of package descriptions vs other things, I agree that package descriptions are usually much lower but they are important for making a first impression. I suggest putting it at the top as usual, but make by default collapsed to a short synopsis (with a "Read More …" button) so that long descriptions don't push the important stuff past the bottom.

  For this it's best to not hide the text directly, but use a div that can be scrolled with a max-height; the button removes the max-height so that it can be viewed in its entirety. This makes the text easily searchable (for both users with Ctrl+F and crawlers).

• In some packages, the dependencies are duplicated several times due to the presence of flags. For packages that require a lot of dependencies, this can become an unreadable blob of text. I think it would help if this were deduplicated somehow.

• Status should really be part of the Maintainer's corner I think.

• Source repository could just be abbreviated as Repository so it doesn't require two lines.

[jberryman]

@bgamari I also like the general minimalist style of hackage/haddocks. Just somehow keeping those items I mentioned in point 2 above the fold would take care of about 70% of my problems.

I hope this issue isn't too obnoxious. Something more helpful would have been to just show a mockup of a different design, but I just had a few minutes and wanted to get my thoughts down.

I really appreciate all the improvements we've seen to hackage recently.

[bitemyapp]

@NathanHowell IMO, we either have Hackage stop with building packages altogether, or it takes full responsibility for docs & builds. I'd rather the former given operational constraints, but I was trying to make the suggestion go along with present circumstances. Also, if we do go with the former, please make the doc gen & upload go with the regular dist upload.

[yogsototh]

A responsive CSS would have been useful for me in more than one occasion. I don't always read package documentation while coding on my computer. It might be a low hanging fruit to make the overall experience better.

[cgag]

I hope I'm using this as intended by doing a brain dump here. I didn't really read the other posts because I wanted to try to think of things with a fresh mind:

• Need a huge red flag if we're not on the current version.
• The title in the upper left should be a link to the contents, possibly the package name should link to the latest version and the version number to the contents of that specific version
  • There should be some sort of standard feature for examples. I've seen them dumped into the docs for the top level module, and I've seen tutorial modules, and often no examples, I'd love if hackage encouraged them.
  • Building the docs should work.
  • The package uploader's name should be a link so I can see what else they've done. I want to see what problems are already solved by people I trust (like BoS).
  • Something like github stars. Possibly just straight up including github stars.
  • Better search. Searching for "config" doesn't find "configurator"
  • Some way to make downloads more meaningful. Is the package itself widely used or is it just used by Yesod?

[dzackgarza]

Hey guys! So this issue is pretty closely related to what I'm working on for this year's GSOC. You can find the proposal in its entirety over at https://github.com/dzackgarza/hackage-server/wiki/GSOC-2015-Proposal:-Improving-Hackage-Discoverability

The mockups mentioned above by @bgamari can be seen here:

Main Page:

http://dzackgarza.com/mockup/main.html

Browse Packages/Search Page:

http://dzackgarza.com/mockup/browse.html

Package Description Page:

http://dzackgarza.com/mockup/package.html

@dcoutts also linked me to this mockup:
http://code.haskell.org/~duncan/hackage-server-new-chrome/package-2.html

I'm currently working on implementing a ranking system on the backend, but I've also allocated some time later in the Summer to improve the frontend - particularly the general search/browse page and the individual package description pages.

I'd definitely like to consolidate whichever features have the most consensus behind them before I make any changes. I'm also collecting some thoughts as issues on my fork, the most relevant one being dzackgarza#3.

That being said, I'll definitely be keeping an eye on this thread, and am open to any and all feedback suggestions, improvements, etc. And don't worry - I'm not married to the color scheme! :-)