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.