New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve appearance and readability #721

Closed
wants to merge 16 commits into
base: master
from

Conversation

Projects
None yet
@NunoAlexandre
Contributor

NunoAlexandre commented Dec 26, 2017

Motive

I work with haddock and hackage almost daily, both at work and at home, and the current theme is unfriendly. I find it very hard to read content with such a wide #content, and spacing is not great either.

Furthermore, I'd say many Haskell developers would appreciate the presense of the latest Haskell's logo (purple) colors in these docs.

Changes

  • use latest Haskell's logo colors
  • decrease #content width to improve readability
  • use, custom nicer font: Merriweather Sans
  • improve sizes and distances

Preview

EDIT 04-02-2018: See #721 (comment)


Using: https://hackage.haskell.org/package/lens-tutorial-1.0.3/docs/Control-Lens-Tutorial.html

Before:

before

After:
after

haddock-after-tablet-standing

haddock-after-tablet-laying

haddock-after-iphone7

@NunoAlexandre NunoAlexandre force-pushed the NunoAlexandre:master branch from 8230549 to 8acf2bd Dec 27, 2017

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Jan 28, 2018

@phadej

A screenshot of https://hackage.haskell.org/package/lens-4.16/docs/Control-Lens-Operators.html with these changes:
screenshot from 2018-01-28 21-42-23

Some bits are not 100%, I noticed. I hope to work on it tomorrow.

@phadej

This comment has been minimized.

Contributor

phadej commented Jan 28, 2018

@NunoAlexandre thanks for the screenshot. It's indeed obvious that some tuning is needed.

@phadej

This comment has been minimized.

Contributor

phadej commented Jan 28, 2018

Also we need to check that

  • Mathematics/LaTeX (I don't remember whether there are packages on Hackage, does @hvr or @alexbiehl remember) and
  • Tables (there aren't yet packages on Hackage using them, but haddock's master supports)

are styled nicely. But that won't be a blocker, rather a thing to keep in mind.


  • I like nice fonts, but I don't like webfonts. caniuse says we can use them https://caniuse.com/#feat=fontface, yet there should be offline fallback which is nice enough.

also Info:

% curl -sL 'https://fonts.gstatic.com/s/merriweathersans/v9/nAqt4hiqwq3tzCecpgPmVZQnJ6jNVR5ny37t9nSm1vT3rGVtsTkPsbDajuO5ueQw.woff2' | wc
     48     307   15808

and there are five (5) variants in the stylesheet.

I don't know whether Hackage would like to host (and whether it can, due font licenses) those on their own CDN, but I don't see bandwidth would be a problem (stylesheet itself is 11k, so styling grows from 11k -> ~70k - not something to worry about).

@cocreature

This comment has been minimized.

cocreature commented Jan 28, 2018

I don't remember whether there are packages on Hackage, does @hvr or @alexbiehl remember

https://hackage.haskell.org/package/kalman-1.0.0.2/docs/Numeric-Kalman.html uses this quite heavily.

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Jan 29, 2018

I am doing some further adjustments, namely darkening the color of the text and making it slighter bigger, changing the color of the links to shades of purple instead of orange, etc. I will push those changes tomorrow, but in the meantime here follows a screenshot of the Control Lenses Operators page:

haddock-lenses-operators

@phadej

This comment has been minimized.

Contributor

phadej commented Jan 30, 2018

I can barely see the code blocks background color. Should I calibrate my display?

@elben

This comment has been minimized.

elben commented Feb 1, 2018

@NunoAlexandre this is in reply to your comments on the other PR. Putting it here because my concerns were largely with the Haddock pages.

I personally cannot recall a case where density was more important than readability, for I would not prefer to see more content at once and have a much harder time reading any of it. I might be wrong here, I am not dismissing your observation.

Do you have an example of a material which is better read with a dense design than with a good negative space that you can show?

I think the current Haddock pages, Hacker News, nytimes.com and is a good example where high-density design works. When I'm in Haddock, my brain is usually in "search" mode. I'm looking for some function I need, or trying to get a sense of what is available. In the same way when I'm scrolling HN or nytimes, I'm searching for something to read. It may not be pretty, but I get what I want out of it quickly and effectively.

A good Haddock example for this use-case is Parsec's combinators. Can you show an example of what that section would look like with your changes?

I am not with you on this one. I have minor studies in typography and (negative) space is fundamental, and a lot of the things you are not into or don't understand have been thoroughly studied and tested. You are obviously free to have your preference, but I am afraid your are not on the winning side of the discussion.
If your point is that I am using too much negative space now, I am open to improve it. But I'd rather have a first version deployed and see what the masses have to say and tweak accordingly, as now the majority seems to like it as I am proposing (which obviously doesn't mean it's right), and democracy rules.

I agree that negative space is important. I also agree that deploy-now-fix-later is a valid approach, as long as we're open and have capacity to improving it later.

I will point out that your mobile example shows where there is too much negative space. The longest line has 42 characters (may be off by one or two), whereas from my understanding good practice is somewhere between 2-3 runs of the roman alphabet (26*2). The padding for the body text seems like wasted space to me, and hurts readability flow.

I agree there is an exageration of low-contrast overall on the web, but I don't see how that is the case here? I think an example of it is, actually, Stackage (which I prefer to look at than Hackage, FWIW), but - again - I can't see how that is a thing on this PR.

I don't have a solid argument or evidence other than I have to squint more with the new contrast, in comparison to the old one.

I wasn't clear before, but overall I think this is a great step forward!

EDIT: ah maybe commenting on this PR was a bad idea. I just saw the updates on mobile's padding

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Feb 3, 2018

Update

I have made some adjustments in order to make this stylesheet consistent with the Hackage one.

Below you can see screenshots of all pages you have asked to see. Note as well the redesigned menu for smaller screens.

Also, I have set the "wider" screen width to 60vw instead of the 55vw on hackage because the hadock pages have more code and less running text in general, making it nicer to have a bit of extra space.

Screenshots

Control.Lens.Operator (mobile edition)
lenses-folds-traversals-smaller

Numeric Kalman:
kalman

Control.Lens.Cons
lens-cons

Control.Lens.Tutorial
lens-tutorial


@phadej, about your note on webfonts: I get that, but it is well-supported as you noted and I have already reduced the number of variants to only 3. The increase in style assets is minimal indeed.


TODO:

  • Fix the tests

@NunoAlexandre NunoAlexandre force-pushed the NunoAlexandre:master branch 2 times, most recently from 758f8ce to 57cf4be Feb 4, 2018

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Feb 4, 2018

Preview latest suggestions

Instead of posting screenshots, I have hosted the pages you guys have shown interest in seeing the latest suggestions here proposed.

You can find a list of links to them following the link below:
https://nunoalexandre.com/2018/02/04/redesigning-haskell-docs#preview

This allows anyone to preview and try it out! I will keep on updating it as we ago so it will always be updated.

@gbaz

This comment has been minimized.

gbaz commented Feb 5, 2018

The live previews are very useful. I think there is a problem with the "synopsis" "contents" listings in the haddocks. The contents are sort of as before, but just look much worse in this new setting, as though they're not fully integrated with the design. Also with everything larger and with more whitespace they just displace more.

image

"synopsis" is just unstyled (rather than being in a nice tab) when unexpanded, and when expanded it also lacks some proper styling:

image

@mightybyte

This comment has been minimized.

mightybyte commented Feb 5, 2018

It makes me really happy to see this. We could definitely use a more modern refresh to the hackage / haddock design. Thank you @NunoAlexandre for your work and raising the conversation here.

At the moment I think the information density argument wins it for me. When I'm looking at haddock pages, I am almost always scanning and want to see more things at once rather than read the page sequentially. Also, type signatures are the most important part of the content. I want to see more type signatures on a page along with maybe a slug of the first paragraph of each function's description.

So while the designs you have so far definitely look better, I think they would make haddock docs less usable for me than they are right now.

@gbaz

This comment has been minimized.

gbaz commented Feb 5, 2018

Personally if I want to fit more in a page, I don't mind hitting cmd-minus a few times to zoom out. The obstacle here seems to be that there's still an undue amount of space between code snippets like in the following:

image

That sort of whitespace doesn't get affected enough by the zoom feature of browsers, so it would be better to just cut it down, imho.

Outside of that, I don't mind the larger font size (since, as I mentioned, its easy to reduce). But I also wouldn't mind a slightly smaller one :-)

I do think the wider margins are a good thing here, as in the haddocks as they stand now, we typically don't have more "information density" (since there's only so much code on each line) but rather just big empty bands of grey that make the stuff flush-left and flush-right much harder to visually associate.

@gbaz

This comment has been minimized.

gbaz commented Feb 5, 2018

I'd also like to see how this handles a degenerate case like this (see the comments pushed all the way to the right by the typeclass instances): https://hackage.haskell.org/package/servant-server-0.12/docs/Servant-Server.html#t:HasServer

(relevant ticket -- #300)

Not to keep inflating scope, but this would be really nice to tackle if its not too invasive to fixup...

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Feb 5, 2018

@gbaz

The contents are sort of as before, but just look much worse in this new setting, as though they're not fully integrated with the design. Also with everything larger and with more whitespace they just displace more.

I am not sure I understand your point here. Are you just suggesting to adjust them to the new design or something deeper? I don't understand how it "looks much worse in this new setting" left alone, thus the question.

"synopsis" is just unstyled (rather than being in a nice tab) when unexpanded, and when expanded it also lacks some proper styling:

Indeed, I have to fix this. Thanks!

I'd also like to see how this handles a degenerate case like this

As soon as I have time I will add it, but it won't be on the top of my list.

Thanks again!

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Feb 5, 2018

@mightybyte

It makes me really happy to see this. We could definitely use a more modern refresh to the hackage / haddock design. Thank you @NunoAlexandre for your work and raising the conversation here.

Thank you very much for your words!

At the moment I think the information density argument wins it for me. When I'm looking at haddock pages, I am almost always scanning and want to see more things at once rather than read the page sequentially. Also, type signatures are the most important part of the content. I want to see more type signatures on a page along with maybe a slug of the first paragraph of each function's description.

I am sensitive to this argument, but note that - as in everything - there is a trade-off being made. By increasing information density we lose readability. And the information that these packages display is not exactly mere superficial text but content that pushes your cognitive load forward, therefore improving readability balances this load. The synopsis (to be fixed) is there exactly for this purpose: for one to get a complete glance of what functions are documented in the current page and to get to them in a click.

I will definitely polish corners here and there to optimize as much as possible both worlds.

Thanks for your feedback.

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Feb 5, 2018

@gbaz

The obstacle here seems to be that there's still an undue amount of space between code snippets like in the following:

I agree, my bad here. I have fixed this already. Thanks for pointing it out!

I do think the wider margins are a good thing here, as in the haddocks as they stand now, we typically don't have more "information density" (since there's only so much code on each line) but rather just big empty bands of grey that make the stuff flush-left and flush-right much harder to visually associate.

I make yours my words.

Thanks

@gbaz

This comment has been minimized.

gbaz commented Feb 5, 2018

I am not sure I understand your point here. Are you just suggesting to adjust them to the new design or something deeper? I don't understand how it "looks much worse in this new setting" left alone, thus the question.

I think it just feels larger and therefore that it displaces more. I'm not quite sure how to fix this -- perhaps it can be left for now. Or maybe the css for the functions can be adjusted so they don't run straight-into the contents, but leave a margin, as the css for the code-blocks does.

@Hrothen

This comment has been minimized.

Hrothen commented Feb 6, 2018

Would it be possible to implement these changes as a flag rather than replacing the current theme? I'd like to be able to retain the current style in docs I build for myself.

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Feb 7, 2018

I have increased the content width a little for all screen sizes and reworked the synopsis. The latter is not great yet but hopefully better and more functional for all use cases.

@lthms

This comment has been minimized.

lthms commented Feb 8, 2018

@NunoAlexandre you are probably aware of it, but if the synopsis is longer than the screen, you can’t see its end. That being said, I really like what you are doing here and look forward to see it merged and used upstream!

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Feb 8, 2018

Thanks, @lthms, I am not able to fix it now but it's now on my list 👍

@cloudhead

This comment has been minimized.

cloudhead commented Feb 8, 2018

Beautiful, thanks for this! I hope we can make it work - I do agree with most comments around space utilization - people use haddock as a tool, so the right information density is important.

@cloudhead

This comment has been minimized.

cloudhead commented Feb 8, 2018

A few observations on your latest preview:

  1. The bolded bits in the code/repl segments with >>> ... draw too much attention compared to the rest. I don't think they need to be bolded.
  2. The synopsis doesn't scroll.
  3. Margin between paragraphs could be smaller to save v-space. Currently looks a bit odd with the one sentence paragraphs which are common.
  4. The text on the topmost menubar is not v-aligned, not sure if it's on purpose but it's distracting.
  5. The top/bottom padding inside code-blocks could be lesser to save v-space, they are quite big.
@igrep

This comment has been minimized.

Contributor

igrep commented Feb 8, 2018

I like most of the design but have one concern: we may lose the way without a link to the index page (top page) on the header.
But unfortunately, it's not achieved by the current haddock/hackage.
Maybe it's not the problem of your design but of the technical design of haddock/hackage themselves...
So I'll file a separate issue if needed.

(I wonder why I've never cared... 😅 ))

@gbaz

This comment has been minimized.

gbaz commented Feb 9, 2018

@igrep i agree that would be a separate issue, but if i understand what you're asking for, that's provided by the "contents" link already?

alexbiehl added a commit to alexbiehl/haddock that referenced this pull request Mar 21, 2018

@alexbiehl alexbiehl referenced this pull request Mar 21, 2018

Closed

Introduce NewOcean theme #782

@alexbiehl

This comment has been minimized.

Member

alexbiehl commented Mar 21, 2018

Please see #782 for the rebased patch set.

@Profpatsch

This comment has been minimized.

Profpatsch commented Mar 21, 2018

Just a heads-up, on 125% zoom (which I quite like for Haddocks), the two-column view currently leaves the screen to the right, while there is some space to the left:

screenshot

Otherwise very good job, I like the new design. I hope it doesn’t break offline docs.

@ericnething

This comment has been minimized.

ericnething commented Mar 21, 2018

@gbaz I cannot agree with you on the font. The choice of font is simply wrong. It is illegible to my eyes and on my screen. Open Sans is an incredibly thin font. Even changing it to something like Lato makes it infinitely more readable. If I have trouble reading the documentation, it may as well not exist, because at that point it is useless. The entire purpose of documentation is to be able to read it and obtain information.

This is near impossible for me to read and hurts my eyes.

screenshot-2018-3-21 introduction hackage 1

Here is what it looks like with 18px Lato (which does not come standard on Mac OS, but there are similar fonts which also have equivalents on Linux and Windows, so there is no need to load a web font).

screenshot-2018-3-21 introduction hackage

On how many eyes and how many displays have you tested your assumptions? I won't back down on the font. It is unacceptable.

Google Fonts should not be used. A third-party proprietary service that tracks you, harvesting and selling data on your activities, has no business being part of open source documentation for an open source programming language. I do not want them involved in any way with my documentation.

@hvr

This comment has been minimized.

Member

hvr commented Mar 21, 2018

@ericnething I'd like to try your 18px Lato font suggestion locally; how do I need to modify my CSS file in order to do that (NB: I'm on Linux)?

@ericnething

This comment has been minimized.

ericnething commented Mar 21, 2018

@hvr I was mistaken that Lato comes standard with Mac OS, but you can download it here. When I have time I can put together a confirmed list of good system fonts and their equivalents for each major OS.

Right-click on any paragraph on the page and inspect it with your web console. It should be under body in the css. Then change it to:

body {
  font-family: 400 18px/1.5 Lato;
}
@gbaz

This comment has been minimized.

gbaz commented Mar 21, 2018

Bear in mind that Open Sans is indeed somewhat light, but the bulk of the difference between the screenshots is that the font-size is just set to be larger in the second one. Honestly I have a hard-time telling the difference between hevetica-alikes and don't feel too strongly about this in any particular way. Even just going with verdana, sans-serif is not too bad. It is also fine for haskell.org to host whatever web font may play a role, or not, in things.

@Profpatsch

This comment has been minimized.

Profpatsch commented Mar 21, 2018

@ericnething I find your conduct to be very condescending.

As for the font, Open Sans is kind of a standard, pretty legible font. Github starts their font-family with -apple-system, BlinkMacSystemFont, , which should probably be copied for Hackage. The sans-serif fallback already exists, so there’s that.

If something is “incredibly thin”, “hurts” a user’s eyes and there’s an “infinitely better” alternative one can download, then there’s always the possibility to use a custom user script.

@NunoAlexandre

This comment has been minimized.

Contributor

NunoAlexandre commented Mar 21, 2018

@ericnething I do think you are exaggerating, not making less of your complaint. The contrast between the text color and the background color is in the highest category there is, and Open Sans is not that light. I do consider your complaint because I once came across this docs and I experienced exactly the pain you describe, but while this is completely crazy, what is now live on hackage is rather standard, acceptable, and fairly high contrast.

About alternative fonts, I'd not go for Lato. It's too "stylish" for such docs, in my opinion. I think that either Source Sans Pro or Helvetica (Nueue) would be a better choice. They are slightly more thick than Open Sans and are also great to read such type of content like this.

Bear in mind that it's impossible to satisfy everyone. My eyes hurt with the previous hackage theme, while you apparently were happy with it. The majority of the feedback we got liked the new theme. A good number of comments about the text contrast was made and addressed properly. Apart from the alternative fonts that I am suggesting above, I don't find it reasonable to make the font bold to make a very small minority happy.

@Profpatsch Profpatsch referenced this pull request Mar 21, 2018

Merged

Stylesheet revamp #693

@Hrothen

This comment has been minimized.

Hrothen commented Mar 22, 2018

Load times are noticeably worse for me with the change. Google Fonts seems like the most likely culprit.

I also agree that the font is too light.

The two column format is very hard to read, at the minimum the metadata column should have a visible border, and the categories should probably be left justified. A better solution would probably be to actually put it on the side instead of sharing space with the description with empty space on both sides.

Actually looking through the metadata column is annoying now. I spent a good ten seconds trying to find the changelog for a package today.

Why not stick with the old format but make the metadata portion collapsed by default, like with typeclasses?

I also really dislike the new color scheme.

The majority of the feedback we got liked the new theme

I just want to point out that the chances that even 10% of people who use Hackage were aware of this change coming are tiny.

@gbaz

This comment has been minimized.

gbaz commented Mar 22, 2018

@Hrothen you are on the haddock issue tracker. If you have comments on the two-col layout, I suggest you comment on a two col layout ticket on the hackage tracker. There are a number of tickets in-flight there. e.g. haskell/hackage-server#721

Vis a vis load times, it can't be google fonts, or at least, it can't continue to be, since they are cached for up to a year. So unless you have turned off all caching in your browser, they should cause negligible load.

@Hrothen

This comment has been minimized.

Hrothen commented Mar 22, 2018

There are a number of tickets in-flight there.

Man, this is way more awkward than one big thread.
So, what. I put my two column layout bits in that ticket and then open my own ticket to say "I don't like the colors"?

@gbaz

This comment has been minimized.

gbaz commented Mar 22, 2018

@NunoAlexandre -- if you want to move to one of the other fonts you suggested, perhaps that might be worth it, since at least this font seems too light for some people? I think the plan of attack -- pushing the tweaks against hackage-server first to get iterative "live" feedback -- and then porting things over here when they are "settled" is reasonable. (btw: commits here should be made against the rebased PR here, I think: #782).

@gbaz

This comment has been minimized.

gbaz commented Mar 22, 2018

@Hrothen I don't think you need to open a ticket to say "I don't like the colors." That would not be a very useful ticket. If you have concrete, actionable, changes, such as proposing a more visible set of colors for links, then that might be useful. Otherwise, you can consider your general dislike of colors sufficiently noted.

@Hrothen

This comment has been minimized.

Hrothen commented Mar 22, 2018

If we're only supposed to open tickets if we have proposed changes, where are you collecting feedback?

@gbaz

This comment has been minimized.

gbaz commented Mar 22, 2018

Your feedback was already given that "I don't like the colors" right here. I don't think that adding it anywhere else will help things.

@Cmdv

This comment has been minimized.

Cmdv commented Mar 23, 2018

@NunoAlexandre I think this is a vast improvement, I know it lacks the 1990's look some are so attached to but my eye wept at the new beauty 😍

@ericnething

This comment has been minimized.

ericnething commented Mar 26, 2018

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.

@gbaz

This comment has been minimized.

gbaz commented Mar 26, 2018

@ericnething Again, for the last time. This is the Haddock repo, not the hackage-server repo. Your comment pertains to two-col layout on hackage server, and is completely irrelevant to this PR. If you make any further comments here off topic, I will delete them. Please comment in the appropriate places, and please do so constructively.

@ericnething

This comment has been minimized.

ericnething commented Mar 26, 2018

@gbaz I am not the only one who is confused about where to provide feedback (see @Hrothen above) since you are spreading out these changes across both repos.

@gbaz

This comment has been minimized.

gbaz commented Mar 26, 2018

Yes, you both certainly have been confused. Hope that things are clearer now.

@ntc2

This comment has been minimized.

Contributor

ntc2 commented May 9, 2018

This PR was closed accidentally, see this comment for how to reopen.

NunoAlexandre added a commit to alexbiehl/haddock that referenced this pull request May 19, 2018

harpocrates added a commit that referenced this pull request Oct 18, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment