Tune styling details

[NunoAlexandre]

Fixes #707
Fixes #715

Preview

These pages are static html hosted on my blog. If you notice some difference in their html structure compared to what is now live on hackage please let me know.

• Hackage homepage
• Browse page
• Monoid Extras package

Changelog

1. Move header .caption above the ul.links (revert of 7c94de4)
   @hvr, I have also cleaned up if-else code around the page title since it seems unnecessary after your these changes of yours: 1cf05f4. Also, since we now will always have Hackage :: [Package] on the left as a link to Hackage's homepage, I removed the "home" link from the right.

2. Tune spacing, typography, and style

   • Move from Open Sans to PT Sans to improve thickness complaints
   • Adjust several elements' font-size to look good with new font
   • Refactor and improve page-header elements positioning
   • Fix @media queries overlap issue
   • Increase body font size as it was too small
   • Reduce #content width for screens larger than 1280px
   • Add new @media query for screens larger than 1920px
   • Improve headings and overall spacing between elements
   • Enrich fallback fonts stack
   • Style search input element

3. Add a new favicon to match the new theme (new favicon to match new theme #707)

4. Make the menu a single and scrollable row (on small screens)
   Instead of breaking the menu links into different lines or forcing the whole header - and therefore page -
   to grow with the overflow of links, the menu is now a single and scrollable row, a la 9gag mobile.

5. Refactor and restyle properties table

   • Improve way of claiming space, which fixes a reported issue when zooming.
   • Opt for a vertical table style to make efficient use of space
   • Improve mobile experience

TODO

• Fix two-column layout issues

There is already a PR addressing this here but, although I don't want to redo or discard someone else's work, maybe it could be solved here together with the rest of the tuning being made.

@gbaz I wonder if we shouldn't, instead, reconsider the 2-col layout. I get where it comes from but it seems it creates more problems than it solves. What do you think?

• Adopt an approach similar to 9gag to deal with the menu links on small screens

Instead of break the links into new lines, we could do something like 9gag does on mobile, by having the list of links in a single line and scrollable (without scrollbar).
Edit: I have implemented it already. Please have a look and see how you like it.

• Reconsider use of webfonts

• Add fallback fonts for Windows and Linux users

• Consider adjusting the properties column table (see Tune styling details #731 (comment))

• Change the :visited links color to #7231AB (see Tune styling details #731 (comment))

• make sure description shows up first in raw html (for screen readers)

[gbaz]

These pages are static html hosted on my blog. If you notice some difference in their html structure compared to what is now live on hackage please let me know.

There is indeed such a change on the package page -- the properties div was moved up so it would be to the right of the package description, rather than below it. It would be good to refresh the local copy of the page to suit this.

[gbaz]

Vis a vis 2-col layout, I wouldn't worry about it in this PR. We can handle that separately. I think I have an idea for a proposal that should suit most of the raised concerns, by combining left-aligning with changing the yellow background for included README files.

[NunoAlexandre]

@gbaz

There is indeed such a change on the package page -- the properties div was moved up so it would be to the right of the package description, rather than below it. It would be good to refresh the local copy of the page to suit this.

Thanks, I have just updated it. If you hard refresh it you will get the latest html and css.

Vis a vis 2-col layout, I wouldn't worry about it in this PR. We can handle that separately. I think I have an idea for a proposal that should suit most of the raised concerns, by combining left-aligning with changing the yellow background for included README files.

Ok, sounds good to me 👍

[gbaz]

I like this overall.

Noticed another glitch though:

(see this in ffox and chrome both)

[NunoAlexandre]

Thanks, @gbaz, it's now fixed.

Note that as I updated the properties table to a vertical table style, I improved the way the properties columns claims and uses space. That solves an issue that was reported about its behavior when zooming the page.

[ericnething]

I am continually frustrated by the most important information being shoved off into a tiny column on the right. Today I wanted to check on what updates have been made to Hakyll, and I had to scroll all the way to the bottom of the page to see when it was last updated, and what the latest version is. The two-column layout is absolutely terrible. Please fix it.

Using Google Fonts is not acceptable for both privacy and security reasons.

[gbaz]

Vis a vis google fonts, the intention is that when we settle on a good font choice -- by the way, in the above you will see a heavier font was chosen, it would be good to know if you consider it an improvement -- we will then rehost it on haskell.org. So it will be a webfont, but with no connection to google.

On making upload date easier to find, I think that the idea in #721 (comment) to move version-relevant stuff to the top would really be helpful here.

[ericnething]

The new font is slightly better than Open Sans, but is also more narrow (like Tahoma) which still makes it less legible than it could be. From what I have read, it was designed for street signs, not dense text.

font: 400 17px/1.37 'PT Sans', -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica, sans-serif;

What about Windows and Linux users? None of these fonts exist outside of Mac systems. The closest equivalent to Helvetica on Windows would be Arial (although a poor imitation), and the closest on Linux would be FreeSans, Nimbus Sans L, or Liberation Sans.

Although I do use and enjoy web fonts, I do not see the point in introducing web fonts for auto-generated documentation. It means you have to host and serve extra data for no tangible benefit to the user (and they have to download it). Given the fact that this is (auto-generated) documentation and not an online book or magazine, what improvement is being made by using a web font? Particularly when it comes to character sets outside of ASCII, most of these web fonts fall short. Choosing sane defaults from the available system fonts is the most logical course of action.

The other issue with web fonts is that most of the free ones are just bad. They are either made by amateurs as a learning project or they are half-assed versions of proprietary fonts released as a marketing tactic (e.g. PT Sans). Helvetica and its imitators might be boring, but they are widely used for a reason — they work.

The only place where I have seen web fonts work well for technical documentation is the Racket documentation and guides. However, the fonts were very carefully chosen and the rest of the design is built around them to maximize legibility. They were not an afterthought.

[gbaz]

@NunoAlexandre What do you think about having the vertical table style revert to the horizontal table with right-aligned headers in the case where the properties table gets pushed inline rather than off to the side (i.e. at a small-enough width)?

[gbaz]

Also: what do you think about this for visited?

Rather than desaturating, I tried to pick a complementary color (#7231AB). I think it pops more without being too obnoxious. Thoughts?

[NunoAlexandre]

@ericnething thanks for your - at last - constructive feedback.

I wrongly assumed there are no Haskellers using Windows and that Helvetica was available on Linux. I am joking about the first and my bad about the second. I will fix it.

The new font is slightly better than Open Sans, but is also more narrow (like Tahoma) which still makes it less legible than it could be. From what I have read, it was designed for street signs, not dense text.

It can always be more legible, but there are trade-offs that need to be made, don't forget that. Long and dense text blocks are not the use case at hand, so I don't make that the number one heuristic. I wonder, though, how reading 300char long lines was apparently fine for you before?

The other issue with web fonts is that most of the free ones are just bad.

True, but I don't think it's the case with the fonts we have been playing with.

Given the fact that this is (auto-generated) documentation and not an online book or magazine, what improvement is being made by using a web font?

In the end, the docs - autogenerated or not - will be read online. And if the cost of providing a better reading experience and look&feel is beneficial it for most readers, than it's an improvement.

I will reconsider the use of webfonts. Despite the conclusion, you can always install a browser plugin that blocks webfonts.

[NunoAlexandre]

@gbaz

What do you think about having the vertical table style revert to the horizontal table with right-aligned headers in the case where the properties table gets pushed inline rather than off to the side (i.e. at a small-enough width)?

I would consider the opposite: revert it to horizontal style on large enough screens. We could also style this specific page layout differently to take more screen space for example.

[NunoAlexandre]

Rather than desaturating, I tried to pick a complementary color (#7231AB). I think it pops more without being too obnoxious. Thoughts?

I like it! 👍

[gbaz]

I would consider the opposite: revert it to horizontal style on large enough screens. We could also style this specific page layout differently to take more screen space for example.

I don't think that's a good idea. The vertical layout resolves the issue with a ragged border, which people found confusing with two-cols. That issue persists even at larger screens, as long as we have two cols.

My idea with the small-screen layout change would be to recover some information density in that case. But I don't feel strongly either way.

If you like the visited change, mind tossing it in with this PR to keep things unified?

[jirassimok]

Right now, the visited links have a higher contrast with the background than other links, which is not usually the case. Reversing the two colors works better, I think.

The new font is all right, but I agree that it is very dense. In particular, the version number list is difficult to read, apparently because spaces following commas are narrower than normal spaces.

My overall impression is that the new font looks nicer at a glance (except for the strange kerning around some punctuation), but is harder to read. This isn't too bad, but it makes it a little harder to find information quickly, or if you are dyslexic. (Also, the tiny, asymmetrical apostrophes and quotation marks bug me.)

The rest of my recommendations are for changes not currently in this pull request.

The modules list would benefit from bullets when it gets narrow enough that text wraps. Right now, the wrapped text is hard to distinguish from non-wrapped text, which makes the list harder to read. Alternatively, you could hide the common prefixes of the modules when it gets that narrow, though that would probably bother someone else.

It might not look as nice, but the package description should be placed before the properties in the DOM. It doesn't matter for general use, but if someone wanted to look at a Hackage page with a screen reader, for example, the description should be the first information shown.

I recommend either restoring the old format of the "uploaded" property, with the date before the uploader, or moving the word "by" into the header. A comma between the uploader and the time would also work to make it clear that the line isn't "uploaded by."

[NunoAlexandre]

Hi @jirassimok!

Thank you very much for your great feedback.

Right now, the visited links have a higher contrast with the background than other links, which is not usually the case. Reversing the two colors works better, I think.

This is a good point. I tried reversing the colors but the visited color is too strong - or so I find. It's not a good choice after all. If one tries to do that and see that color used for all links in the page will understand.

Edit: I have change it now, and IMO it looks sensible and better too, also when all links are visited and have this new color.

The new font is all right, but I agree that it is very dense. In particular, the version number list is difficult to read, apparently because spaces following commas are narrower than normal spaces.

I have fixed this, thanks!

My overall impression is that the new font looks nicer at a glance (except for the strange kerning around some punctuation), but is harder to read. This isn't too bad, but it makes it a little harder to find information quickly, or if you are dyslexic.

I have made it less dense and I have worked on the kerning. Could you have another look?

(Also, the tiny, asymmetrical apostrophes and quotation marks bug me.)

Can you point me an example, please?

---

It doesn't matter for general use, but if someone wanted to look at a Hackage page with a screen reader, for example, the description should be the first information shown.

This is a very good point. I worked on a project thought for blind people and this sort of details for the general user makes a whole difference for them.

[gbaz]

I added a todo for the description-first in raw html. We can continue to discuss and tune and fix things going forward, but I'm going to merge these changes for now so we can do a deploy soon and get more iterative feedback.

[AphonicChaos]

In general, I really appreciate the two-column layout, as it requires less scrolling to get to documentation and removes focus on meta data (while still providing it when I am interested in it). That said, a few things bother me:

1. The font choice makes "q" difficult to recognize -- I mistook it for an underlined O initially:
   
2. The actual documentation being rendered with a different color scheme is a bit jarring.
3. Similar thing for the size of the header and margins surrounding it.

I guess for 2 and 3 above, we'd have to see similar improvements made to haddock itself? I'll admit that 1 is rather nit-picky, but I spent a few minute trying to understand why font rendering on my machine was broken before realizing it was simply the choice of font!

[NunoAlexandre]

Hi @Aspidites,

Thanks for reporting this.
I just checked the page of your screenshot and although the Q still is, indeed, a tiny little bit odd, it's nothing compared to what I see in your screenshot. This is how it looks on my machine:

Could you let me know which OS/monitor you are using?
Thanks

[AphonicChaos]

Let me know if you need anything else.