rustdoc font is too large and serif and not crisp

[mahkoh]

Currently is looks like this:

16px/1.4 "Source Serif Pro", "Helvetica Neue", Helvetica, Arial, sans-serif

• It's very large, meaning that you have to scroll more, see less documentation at the same time
• It's serif. This is documentation and not the New York Times.
• It's hard to read.
  1. The rendering is not good. This might be a problem with my setup but I don't have this problem on any other side. Look at the 'G' in particular.
  2. It looks bold.

Now compare this to

12px sans-serif

• Crisp
• Easy to read
• Used just about everywhere

Thoughts?

[doy]

The rendering looks fine (and not bold) on my end:

Also, the serif vs sans issue isn't just a style thing, serif fonts are easier to read at higher resolutions and larger font sizes (so your first two points are actually related).

[mahkoh]

My screenshot above was from chromium. This is what it looks like in firefox:

This is certainly better. 12px sans-serif:

[steveklabnik]

12 points is far too small. The size is just fine, imho.

And why can't our docs be the new york times? ;)

[mahkoh]

Not 12pt, 12px.

MDN uses 14px. reddit uses "small" which is 13px here. github uses 14px. HN uses 9pt. Google uses "small". Gmail uses 80% of "medium". The example code on rust-lang.org is 13px.

[mahkoh]

Point being: All of those websites are read by billions of people every day and their fonts are much smaller than what rustdoc produces (on this system.) If absolute px sizes don't scale to high DPI displays then use "small" which works fine on reddit.

[steveklabnik]

I mis-read. I prefer 16pt for fonts, personally. Regardless, I think that the 12 is far too small.

[mahkoh]

Please try "small" (with both fonts.)

[ftxqxd]

If we’re getting into an argument about typography, I would recommend reading Butterick’s Practical Typography, which certainly recommends larger font styles. (It actually has an example of what Python’s documentation should look like. It also states that the font size should change depending on the window size; I agree with this.) It also uses sans-serif for the body font; I agree that using a sans-serif font (Source Sans Pro?) is certainly better than the current serif font, which doesn’t really fit with the rest of the page. All those sites have flaws or reasons to be using small fonts:

• Frankly, Reddit has a terrible design. It should not be used as an example.
• MDN’s 14px is quite close to our current 16px. IMO it’d be better with a slightly larger font.
• Github isn’t really designed for reading large amounts of text.
• HN’s design isn’t great either.
• I think that Gmail could probably do with a larger font; it looks a bit too dense for my liking.

It is incredibly strange that currently the font is defined as a serif font, but falls back to a sans-serif font if that font can’t be retrieved.

[mahkoh]

Have no respect for the authority of others, for there are always contrary authorities to be found.

All jokes aside, typography is probably one of those fields where one can find those contrary authorities.

It also states that the font size should change depending on the window size; I agree with this.

I tried this on his website and was surprised to find that, the larger you make the window, the less content is visible. This is kind of the opposite of the usual Web 3.5 tick where making the window smaller hides content.

Source Sans Pro?

I don't understand why rustdoc needs a fancy font. I've already shown above that those fonts look horrible on Arch Linux with Chromium and stock freetype2. It appears to me that the webdevs are using rustdoc as a playground for their new Web 4.0 ideas (responsive design, fancy web fonts, "web-typography", whatever.) When you make then window smaller suddenly the sidebar disappears which is essential for navigation. The descriptions of modules and functions are hidden behind "..." when they reach the window border because someone thought that looks good and who doesn't like navigating all over the place to read the descriptions?! Rustdoc doesn't produce prose. It's not even a tutorial. It's a reference. And as a reference it has to be all about conveying/finding/skimming a lot of information quickly. It cannot do this when you have to scroll and navigate all over the place. The (mostly excellent) search function is its redeeming feature in this regard.

Frankly, Reddit has a terrible design. It should not be used as an example.

Design? See above.

Github isn’t really designed for reading large amounts of text.

Neither should rustdoc. This thread alone might already contain more text than you'll usually read on a day via rustdoc.

[steveklabnik]

Rustdoc doesn't produce prose. It's not even a tutorial.

This is very much not true for things like module-level documentation, which often do have large amounts of text. And there's only going to be more once I get done with it 😉

[mahkoh]

The stdlib docs might have a bit of a split personality here. A random survey of rust-ci shows that this is not usually true. And even with the stdlib: You read the long description once, twice, maybe thrice and that's it. The 99% use-case for rustdoc is as a reference.

[ftxqxd]

All jokes aside, typography is probably one of those fields where one can find those contrary authorities.

This is a good point, but I’ve yet to see an experienced typographer recommend using 12px fonts on a website.

I tried this on his website and was surprised to find that, the larger you make the window, the less content is visible.

It’s not about resizing the window, it’s about different screen sizes. Typically, a larger width means a larger screen/resolution, which means that there is enough space to fit larger text into.

I don't understand why rustdoc needs a fancy font.

There are numerous reasons for this—the page needs to be consistent across many browsers (to make styling more easy, and also just for consistency reasons), so the font needs to be explicitly specified. Using a system font is generally not a good idea—Arial and Times New Roman, some of the most widely-supported fonts, are well known for being awful. Using a ‘fancy font’ means that we can actually get a font that is good.

I also don’t understand your problem with font rendering right now—not only does the rendering look fine to me (Firefox 34 on Ubuntu 14.04), it looks fine in your screenshot.

It appears to me that the webdevs are using rustdoc as a playground for their new Web 4.0 ideas (responsive design, fancy web fonts, "web-typography", whatever.) When you make then window smaller suddenly the sidebar disappears which is essential for navigation.

Ever wondered why those ideas exist? Responsive design is essential to make the page work for mobile browsers. Web fonts exist to avoid having to use system fonts, which can’t necessarily be relied on, and the ones that can are typically awful or overexposed.

The descriptions of modules and functions are hidden behind "..." when they reach the window border

I agree that this should change.

as a reference it has to be all about conveying/finding/skimming a lot of information quickly.

I expect you’ll like #16169 then.

The 99% use-case for rustdoc is as a reference.

Yes. The process goes something like this:

1. Search up function/type/trait/whatever.
2. Select relevant result.
3. Read description.

Step 3 is the only step here where the font matters. And to make reading the description easier, we have 16px web fonts. Making the font a smaller system font will not help legibility.

[steveklabnik]

Yes, most people don't write good docs. That doesn't mean we should make the tool encourage that.

[mahkoh]

This is a good point, but I’ve yet to see an experienced typographer recommend using 12px fonts on a website.

I guess you're right. When I suggested 12px I didn't think about high DPI displays. But "small" seems to be working fine for many websites.

It’s not about resizing the window

On his website it is. When you make the window larger the text grows vertically so that less text is visible.

the page needs to be consistent across many browsers (to make styling more easy, and also just for consistency reasons)

For what purpose? Github tries to use Helvetica but I'm using DejaVu Sans everywhere and it looks just fine.

it looks fine in your screenshot.

It's blurry. Maybe you're using a high DPI display where this isn't visible but it certainly is on my screen. I've never seriously use a website with a font as blurry as the one used by rustdoc.
And it's not even consistent across browsers as the screenshots in this thread show.

Ever wondered why those ideas exist? Responsive design is essential to make the page work for mobile browsers.

No it's not. Here: http://blog.fefe.de/ It just works. Responsive design becomes necessary when you break everything with CSS and have to fix it somehow. And since you're not programming on your phone this is a non-argument. (consider creating a completely separate website for those who do program on their phone, like m.wikipedia.org or something like that.)

overexposed

A font people are used to in technical documentation? We can't have that, I guess. Time to tell the journals to ban Computer Modern.

I expect you’ll like #16169 then.

Very much.

Yes. The process goes something like this:
Step 3 is the only step here where the font matters.

Not quite. You have to discover what functions exist. This means being able to quickly skim the list of functions. Making the font smaller will put more functions on the screen. See the docs for Vec.

[mahkoh]

Yes, most people don't write good docs. That doesn't mean we should make the tool encourage that.

Rustdoc is not a tool for reeducation.

[mahkoh]

This isn't going anywhere. The current font and font-size make the docs subjectively much worse on my system. Let's just wait for what other people have to say.

[ftxqxd]

But "small" seems to be working fine for many websites.

For me, ‘small’ is 13px. That is hardly better than 12px.

When you make the window larger the text grows vertically so that less text is visible.

What I meant is that most of the time, people don’t resize their browser window. Window size is generally proportional to screen size/resolution, and with more horizontal space comes more vertical space. The font is made larger to make approximately the same amount of information appear on the screen for any given size. Also, a larger screen resolution often means a higher DPI, so that fonts look smaller. For this reason, the font is made larger for higher resolutions.

For what purpose?

So that we can rely on e.g. the width of any character. So that random people don’t complain about the font looking bad because their system doesn’t support whatever other font is intended.

Here: http://blog.fefe.de/ It just works.

That site is inherently responsive. It has no content that wouldn’t work on all screen sizes. But rustdoc has a sidebar which would not work at all on a mobile device. Is this what you would prefer?

The argument about people not programming on mobile devices is not exactly valid; people could be answering StackOverflow/Reddit/IRC questions on their phone, or maybe they are coding on a mobile device. There is almost always a use case for it. Creating a separate website would only cause problems with links, and complicates things unnecessarily. How is that better than the current situation?

Making the font smaller will put more functions on the screen.

Having more functions on the screen doesn’t help in the slightest; I can still only read one thing at a time. If I want to skim through the names of functions, and not the descriptions, I can collapse all of the descriptions (well, I will be able to soon) and skim through the names. Decreasing the font size is the wrong solution.

(I agree that this argument is not going anywhere. But if it’s just you who has this problem, then there’s no point in arguing about it.)

[Gankra]

Honestly, if you don't like the information density, can you not just zoom in/out? Rustdoc seems to behave very well under these conditions. This is also an effective shim to resolve your issue with #16174.

[mahkoh]

I'm already doing this but you might as well ask why people don't simply zoom in if they think the text is too small. @P1start is probably already doing this on, e.g., reddit because he thinks the font is too small. I could even write a small script that changes the font of the stdlib docs, but this issue is about the default settings.

[ftxqxd]

After playing around with rustdoc’s fonts, I realised that I would actually be fine with it if the font were changed to 14px Source Sans Pro. A comparison of the current style, 16px sans and 14px sans (click to embiggen):

Although I do prefer the 16px style, I have to admit that the majority of sites seem to have a font size around 14px (Github, MDN, etc.) so I think that the 14px option is probably best.

I will make a PR unless anyone has any complaints/better alternatives.

[steveklabnik]

I still prefer the serifs, and the size.

[ftxqxd]

Whoops—turns out I was using some other sans-serif font instead of Source Sans Pro. I’ve updated the comparison above, and I now think that 16px sans-serif is the best option (because Source Sans Pro seems to be a bit smaller than the other font I was using).

Edit: I cobbled together a before/after slider thing here.

[liigo]

I prefer big font than smaller one

[mahkoh]

I've hacked a high contrast, high information density css that just works (modulo bugs): https://gist.github.com/anonymous/aee905e84aa54745e81b

To test it you'll probably have to block the original css file.

[doy]

I also prefer the serifs and the current size - those images seem very cluttered. Also, wrapping around the sidebar like that makes it quite a bit harder to skim, since things are no longer always vertically aligned.

[Ericson2314]

I don't mind the fonts face, but I do find the text a bit big. Since people started focusing over mobile there seems to be a trend towards bigger text, but I exclusively view the docs on a desktop/laptop, where I value more information density first and foremost.

[mahkoh]

See also #16372