rustdoc font is too large and serif and not crisp #16173
Description
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.
- 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.
- It looks bold.
Now compare this to
12px sans-serif- Crisp
- Easy to read
- Used just about everywhere
Thoughts?
Activity
doy commentedon Aug 1, 2014
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 commentedon Aug 1, 2014
My screenshot above was from chromium. This is what it looks like in firefox:
This is certainly better. 12px sans-serif:
steveklabnik commentedon Aug 1, 2014
12 points is far too small. The size is just fine, imho.
And why can't our docs be the new york times? ;)
mahkoh commentedon Aug 1, 2014
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 commentedon Aug 1, 2014
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 commentedon Aug 1, 2014
I mis-read. I prefer 16pt for fonts, personally. Regardless, I think that the 12 is far too small.
mahkoh commentedon Aug 1, 2014
Please try "small" (with both fonts.)
ftxqxd commentedon Aug 2, 2014
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:
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 commentedon Aug 2, 2014
All jokes aside, typography is probably one of those fields where one can find those contrary authorities.
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.
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.
Design? See above.
Neither should rustdoc. This thread alone might already contain more text than you'll usually read on a day via rustdoc.
steveklabnik commentedon Aug 2, 2014
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 commentedon Aug 2, 2014
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 commentedon Aug 2, 2014
This is a good point, but I’ve yet to see an experienced typographer recommend using 12px fonts on a website.
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.
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.
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.
I agree that this should change.
I expect you’ll like #16169 then.
Yes. The process goes something like this:
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 commentedon Aug 2, 2014
Yes, most people don't write good docs. That doesn't mean we should make the tool encourage that.
mahkoh commentedon Aug 2, 2014
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.
On his website it is. When you make the window larger the text grows vertically so that less text is visible.
For what purpose? Github tries to use Helvetica but I'm using DejaVu Sans everywhere and it looks just fine.
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.
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.)
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.
Very much.
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 commentedon Aug 2, 2014
Rustdoc is not a tool for reeducation.
mahkoh commentedon Aug 2, 2014
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 commentedon Aug 2, 2014
For me, ‘small’ is 13px. That is hardly better than 12px.
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.
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.
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?
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 commentedon Aug 2, 2014
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 commentedon Aug 2, 2014
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 commentedon Aug 2, 2014
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 commentedon Aug 2, 2014
I still prefer the serifs, and the size.
ftxqxd commentedon Aug 2, 2014
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 commentedon Aug 2, 2014
I prefer big font than smaller one
mahkoh commentedon Aug 3, 2014
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 commentedon Aug 3, 2014
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 commentedon Aug 3, 2014
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 commentedon Aug 14, 2014
See also #16372