search

rust-lang / rust

Empowering everyone to build reliable and efficient software.
https://www.rust-lang.org
Other
99.16k stars 12.8k forks source link

Proposal: largely revert the recent docs style changes #13780

Closed chris-morgan closed 10 years ago

chris-morgan commented 10 years ago

12996 was the main rustdoc style alterations, then #13485 was landed making most of the changes.

When the changes landed, feedback was definitely mixed. A few people said they liked it, but I feel that most of the feedback was slightly negative. In the ten days since then, I believe I have in IRC heard one positive opinion and on quite a few occasions (at least half a dozen, which I would consider quite a large number) distinctly negative opinions, some of things that at the time we thought that we could live with but are discovering that, having given it time to sink in, it really is worse. At first glance, the changes may look nicer (I don’t know—I didn’t find it so, overall), but we have lost a lot of utility and character in it.

I want us to change our direction and mostly go back to the old styles.

Here are my three main reasons for saying, “The old is good”:

This is mostly separate from issues like the reduction of information density (#13591)—that can be improved upon without going back to the old layout, though I rather suspect that with the everywhere‐is‐white approach, usability will be hindered further by more dense information. But I cannot reasonably hold that as a point against the new design until it has been tried.

I propose, then, that we revert almost all of the style changes. I would still keep the lightening of the grey background in the main body area (not in the sidebar by any means), though I would prefer it not to be taken quite to white—rather, swap its background colour with that of the code blocks, as they were back then. Not lessening anyone’s contributions to either design in any way, I believe that the earlier design was largely more appropriate for Rust.

No decision should be reached terribly rapidly on this matter; it would be well to try to gauge what people actually feel about the matter; it may be that, given the threat to the new design, people will flock to support it and it be revealed that I am actually incorrect. It is always hard to judge such things. Most people will always be silent.

/cc @TheHydroImpulse @adrientetar @brson @huonw @cmr @Seldaek

chris-morgan commented 10 years ago

I’ve posted this on /r/rust to get a broader audience in on the matter; a comment which I’ve made some form of poll will be particularly interesting.

bachm commented 10 years ago

The new style is sterile, whereas the old one had character (and was also more readable).

liigo commented 10 years ago

I'd like +1 for this 2014年4月26日 下午10:32于 "Chris Morgan" notifications@github.com写道：

12996 https://github.com/mozilla/rust/pull/12996 was the main rustdoc

style alterations, then #13485https://github.com/mozilla/rust/pull/13485was landed making most of the changes.

When the changes landed, feedback was definitely mixedhttp://www.reddit.com/r/rust/comments/23c9nu/new_doc_design_is_live/. A few people said they liked it, but I feel that most of the feedback was slightly negative. In the ten days since then, I believe I have in IRC heard one positive opinion and on quite a few occasions (at least half a dozen, which I would consider quite a large number) distinctly negative opinions, some of things that at the time we thought that we could live with but are discovering that, having given it time to sink in, it really is worse. At first glance, the changes may look nicer (I don’t know—I didn’t find it so, overall), but we have lost a lot of utility and character in it.

I want us to change our direction and mostly go back to the old styles.

Here are my three main reasons for saying, “The old is good”:

-

Things were separated into blocks that could be perceived individually, much more effectively. In some places this went a little too far, and I would be in favour of changing the main content’s background from grey to a very light grey, but taking out all blocks is significant hindrance to usability. The structure of all the content is very significantly important; being able to quickly navigate around.

The old design had character. The bottom borders on things, the distinct colour scheme, the fonts—they all felt like Rust. I draw particular attention to the blocky font used in the headings; that font was a very good font choice and fits in with the Rust name, logo ( especially the logo), &c. More changes to the new styles are being proposed, but the changes are still just feeling tacky and generic—they don’t feel like Rust.

Character is a surprisingly important thing, and at present we’ve lost it. I think we should be looking rather at changing the styles of the non-rustdoc docs to make them feel like Rust. I hope you understand the abstract concept that I am getting at.

Not only did the font choices have character, they were also easier to read the structure of the page from. This has also contributed to it being more difficult to read things.

This is mostly separate from issues like the reduction of information density (#13591 https://github.com/mozilla/rust/issues/13591)—that can be improved upon without going back to the old layout, though I rather suspect that with the everywhere‐is‐white approach, usability will be hindered further by more dense information. But I cannot reasonably hold that as a point against the new design until it has been tried.

I propose, then, that we revert almost all of the style changes. I would still keep the lightening of the grey background in the main body area ( not in the sidebar by any means), though I would prefer it not to be taken quite to white—rather, swap its background colour with that of the code blocks, as they were back then. Not lessening anyone’s contributions to either design in any way, I believe that the earlier design was largely more appropriate for Rust.

No decision should be reached terribly rapidly on this matter; it would be well to try to gauge what people actually feel about the matter; it may be that, given the threat to the new design, people will flock to support it and it be revealed that I am actually incorrect. It is always hard to judge such things. Most people will always be silent.

/cc @TheHydroImpulse https://github.com/TheHydroImpulse @adrientetarhttps://github.com/adrientetar @brson https://github.com/brson @huonw https://github.com/huonw @cmrhttps://github.com/cmr @Seldaek https://github.com/Seldaek

— Reply to this email directly or view it on GitHubhttps://github.com/mozilla/rust/issues/13780 .

Seldaek commented 10 years ago

Disclaimer: I am obviously biased having done the initial version of the old design, and I haven't followed the discussion at all on the new one since I have been a bit out of touch with rust lately.

But yes, while I would say the new design is shinier, I don't think technical documentation has to be shiny, it has to be usable/readable, and I do feel the flattish design all white approach loses on that aspect. I think the old one was already kinda fancy when it comes to a documentation layout.

IMO design time would be better spent on the http://www.rust-lang.org page which could use a more appealing first impression. As long as the critical links remain easy to find that is :)

vky commented 10 years ago

I think the new style of docs is an immense improvement over the old style. The larger and more spacious font makes reading the docs much easier, and more pleasing. I disliked the previous blocky and tight header font, and the general text itself I found to be smaller than I would like. The new style is also more smart-phone friendly. The small lettering of the previous style required more futzing around with to be readable on a phone.

(For reference, I generally use two 24in 1920 x 1200 monitors.)

I found the gray and white backgrounds of the old scheme was slightly distracting compared to the new all white scheme. Colored words stand out much better now against the pure white background, than they did on the gray background. There was a tightness, a confined feeling, with the gray background that encapsulated the content and navigation pane, then being further encapsulated by the remainder of the page being white.

As for character, my personal image of Rust is primarily "modern" and "practical". I feel that the new doc style accomplishes that far better than the old style.

huonw commented 10 years ago

Some issues related to the fancy new fonts in the new style https://github.com/mozilla/rust/issues/13593 https://github.com/mozilla/rust/issues/13787.

I did like the character of the older design, the fonts felt Rust-ier (although that may be partly because I'm using firefox and so hit #13593 and don't see the new ones).

adrientetar commented 10 years ago

What @vky said ties into my personal feelings.

When the changes landed, feedback was definitely mixed.

The post got 81% upvotes (as of now), it's a pretty good score for a design change imo – design is always controversial.

The old design had character.

Can't say otherwise, but webfonts here (once they work properly... see issues referenced by @huonw) are giving uniqueness to it, minimalist and readable design too. Just look at the majority of today's websites, they have small point sizes for the body, they have colors and ads all over the place that distract the user from the actual content. Is you were writing a paper specification, would you put colors and fanciness all over the place? The web is no different to me. Designing a website focused on content is what makes it truly unique, and readable at the same time.
Now sure, I am not personally opposed to making some style tweaks. Fonts, code color scheme... this is what makes it truly unique imo, the rest is bloating.

Like @huonw said, there are some issues with the fonts right now so most of you may not be able to see them. I am working on the fallout of the new design and on fixing this (through I don't exactly know how to make the server pickup and upload the fonts – my attempt in # seems like it wasn't successful – cc @brson).

Lastly, I will quote some of the principles I stand against behind the current design – even though the original work is @TheHydroImpulse's – from reddit:

The new design is content-centric, using the typical typography guidelines – a process similar to the one fleshed out by the 1910 studio. This ties into the guidelines shown by Matthew Butterick: a content-centric internet and it has nothing to do with Bootstrap specifically, it's just about doing away with default browser-styles and raising the font-size to have a proper view and better readability of content. Scrolling a bit more often is not an issue when you have a significantly more comfortable readability and less bloat.
It is a minimalist and content-centric design, not a Bootstrap design. What's like Bootstrap: underline under the headings, the search bar highlights in blue when you click it.

Having a higher point-size is crucial now that we the minimum common denominator in terms of screen is "decent". Please read this article by SmashingMagazine that goes more into technical details with this matter, also most importantly this article about responsive typography which is very comprehensive about point size, margins and how it should be set.
No typographer, no designer will tell you otherwise and you'll see yourself having less trouble to concentrate and less squint when reading a text that has appropriate point size (16px and higher) and proper, aerated but not exaggerated line-height (120-145% – of prime importance for readibility and when jumping to the next line of text).

That's the gist of it—now of course I am committed to making the “best and most-efficient” content for everyone and not just me so I will let @brson voice out what he thinks is wise.

huonw commented 10 years ago

The post got 81% upvotes (as of now), it's a pretty good score for a design change imo – design is always controversial.

That design change post was the very first time people had used it, and initial reactions may be different to the actual experience of using them for a little time. :)

iliekturtles commented 10 years ago

The font changes cause wrapping issues with some of the wider diagrams. See the linked list diagram at the end of section 9.1 in master (http://static.rust-lang.org/doc/master/tutorial.html#boxes) vs .10 (http://static.rust-lang.org/doc/0.10/tutorial.html#boxes).

This can easily be fixed if doc style changes are not reverted but lead me to another issue where the "Source Code Pro" font is not monospace in Chrome on Linux. Firefox on Linux, Chrome/IE on Windows 7, and Chrome/Safari on OS X all work properly. The generated .html file includes <link href='http://fonts.googleapis.com/css?family=Source+Code+Pro:400' rel='stylesheet' type='text/css'> so this may be a Linux specific rendering issue.

adrientetar commented 10 years ago

Please note that webfonts (except Source Code Pro) are not working yet. We are working on resolving this issue.

In the meantime, please look at these samples that include working webfonts:

(We need to edit static.rust-lang.org apache conf to allow serving WOFF files.)

The font changes cause wrapping issues with some of the wider diagrams. See the linked list diagram at the end of section 9.1 in master (http://static.rust-lang.org/doc/master/tutorial.html#boxes) vs .10 (http://static.rust-lang.org/doc/0.10/tutorial.html#boxes).

Thanks for the report. It is not the font itself but the font-size (15px on 992px+ wide screens). I made it so that it would allow displaying 80 chars on a single line (as is the convention on rust src) but the documentation does not seem to follow this convention... I have fixed these overflowing instances as part of #13776.

nham commented 10 years ago

The new design has some wins: the new font is nicer, and the bigger font sizes are a definite improvement. One thing I see is that the code examples are now harder to distinguish from the rest of the page. Compare http://adrientetar.legtux.org/cached/rust-docs/struct.CChars.htm and http://static.rust-lang.org/doc/0.10/std/c_str/struct.CChars.html. I'm not a designer, but to my eyes the new page is harder to read. The example code blocks need to be set off somehow, either with more whitespace or a different background color.

adrientetar commented 10 years ago

@ndam Interesting, so in your opinion the code blocks should stand out with a slight grey background like it was before (i.e., after redesign but before recent changes)?
I thought the slight border and monospaced font along with the "Example" and so forth headings would set it off while keeping it in the page flow.

Maybe this behavior should be kept in the written docs while preserving a light grey background for rustdoc itself?
I think it makes sense to make code stand out on rustdoc where you might want to look for it specifically (unlike tutorial and so on). If so, I'll update my current PR with that change.

yuriks commented 10 years ago

I'll have to disagree with that the current font size is readable. It is most comfortable for me if I reduce the zoom by one or two notches in Firefox. (With Ctrl-scroll wheel or Ctrl-minus.) The current size (even with the fixed fonts in @adrientetar's links) is too large to read comfortably to me. The information density is too low for the amount of eye movement required.

I suspect this has a lot to do with the display the developers of the style are using. Informal pool: Who here uses a high-dpi laptop display? a low-dpi laptop display? a desktop monitor (which all have around 96dpi afaik)? What is your opinion on the font size?

(Desktop monitor here.)

thehydroimpulse commented 10 years ago

I'm currently using a retina macbook pro, and quite enjoy having bigger fonts. I'm a pretty picky person when it comes to typography and the old design didn't have a good focus on typography. Though I still think the typography needs some work; however, I'm worried that it will become a design by committee, which doesn't end well — at all. In the end, design is somewhat subjective. However, I think there's a good standard that many people have agreed is good design (web design specifically).

Here are some links I've collected that demonstrate some strong typography:

I think there needs to be some changes to the current font size. The space isn't used effectively IMO.

The biggest thing right now is "what's the goal/vision?" I find the best designs have a singular goal/vision from the get go. The issue with providing tweaks here and there is that the vision gets lost and nothing becomes clear on what the goal truly is.

For example, if we set out with the goal of being extremely comfortable to read and look at (i.e., you want and love to look at it. It clear, it makes sense), then we might get to an entirely different design.

Hopefully we won't get lost along the way and it doesn't become a mess of inconsistencies and "tweaks" everywhere.

adrientetar commented 10 years ago

Font-size should be scaled by browser w.r.t. DPI.

alxgnon commented 10 years ago

I'm using a 1280x800 px laptop screen right now. I also believe the fonts are way too big. The current theme looks nice, but I honestly think the bulk of text looks better (and is easier to read) in Helvetica Neue than in Heuristica. After all, Helvetica and its derivatives are well tested and familiar fonts. Also, Heuristica is a serif font. Although great for printing, serif fonts are (arguably) harder and less pleasing to read on computer screens, compared to sans-serif.

Obviously opinions will differ on what to "tweak" or not. I agree with @TheHydroImpulse. We need to know where we are going. And we need a lot of opinions.

I'm personally going to play with the css on a copy of the docs that ship with Rust for the next hour or so, and compare it to other documentation styles I like.

adrientetar commented 10 years ago

Although great for printing, serif fonts are (arguably) harder and less pleasing to read on computer screens, compared to sans-serif.

No, as long as you have 12pt or higher point size. The serifs' horizontal geometry help guiding lecture.

They have been historically left out because early computer screens had really bad resolutions so it was easier to use no-frills, sans-serif fonts. Common domestic printer resolution today is 600dpi, as long as you approach 100 dpi the serifs have their turn.

See Practical Typography, Responsive Typography and A Reader-first Internet.
The Shape of Design is another web book example. For a more relevant example to our matter, Racket docs use a serif typeface.

Though I have to agree that rustdoc is different since it's code documentation, not raw documentation itself. It's often shorter and meant for a quick glance (?) so I introduced some changes as part of #13776:

I updated my cached copy with these changes, e.g. here is struct.CChars.

adrientetar commented 10 years ago

Here is a shot of Racket equivalent to rustdoc: http://docs.racket-lang.org/turtles/Traditional_Turtles.html#%28def._%28%28lib._graphics%2Fturtles..rkt%29._draw%29%29

yuriks commented 10 years ago

That one looks much better. The grey background makes a huge difference in one's ability to scan the page. (Example blocks tend to act as separators between each function.) The text is also easier to read, though the font doesn't have very flattering hinting (view the full-size image): docs_screenshot

I played around with the CSS and either 14px or 16px work better (there isn't the extraneous noise on ascender/descenders and some of the serifs). However 14px is, I admit, a bit small (though still readable for me, serif get in the way a bit at this size). I could live with 16px.

I don't know if there's much that can be done to fix the hinting at 15px, but that would be ideal.

adrientetar commented 10 years ago

I don't have it on my system (Windows 8 x64, Firefox – Chrome works also), through I expect that the absolute size varies with the actual DPI...

rustdoc

What are your system specs exactly?
This font was made by Adobe, it should have proper hinting (I can try to pass it on ttfautohint otherwise).

yuriks commented 10 years ago

Windows 8 x64. Firefox and Chrome both exhibit the issue. (Though Chrome has a slightly lighter rendering.) I use a single 27" 2560x1440 display. (Which has ~109 PPI, pretty sure Windows just pretends it has 96 DPI, I don't use DPI scaling.)

The font in your screenshot is much larger than the text in mine. Do you use a high-density display?

adrientetar commented 10 years ago

1920x1080, 13" so that makes ~170DPI. Firefox seems to scale the content while Chrome does not.

I can see the same thing as you in Chrome, indeed.

adrientetar commented 10 years ago

I opened up an issue about the hinting flaw: https://code.google.com/p/evristika/issues/detail?id=13

nwin commented 10 years ago

@adrientetar why are you using px and not pt for the font size? pt scaling should work better than px scaling, affair. That said, 15 px aka 12 pt is already much better… :)

steveklabnik commented 10 years ago

I actually like the new design a lot more. shrug

thehydroimpulse commented 10 years ago

The old design had character. The bottom borders on things, the distinct colour scheme, the fonts—they all felt like Rust. I draw particular attention to the blocky font used in the headings; that font was a very good font choice and fits in with the Rust name, logo (especially the logo), &c. More changes to the new styles are being proposed, but the changes are still just feeling tacky and generic—they don’t feel like Rust.

There's a fine balance between striking a rust look and an appropriate design for 2014. The thing is is that the old design certainly didn't feel like 2014.

I also disagree with the previous massively bold fonts. It wasn't a page where I wanted to look at. I believe that's what documentation should be. You want to use it because it makes sense, the old design certainly didn't have that feel.

Take a look at the Julia docs (although not an API documentation) http://julia.readthedocs.org/en/release-0.2/manual/introduction/.

You can easily identify their goals:

I don't think there's any vision for the current Rust docs. And I think that'll hurt.

I don't think the current design is done, because it still needs a lot of work. But I do think it's better than before (especially once the bugs are fixed — which I haven't experienced.)

adrientetar commented 10 years ago

@yuriks Settled on 15.5px to workaround the issue.

brson commented 10 years ago

I don't have a lot to say here.

Firstly, @adrientetar and @TheHydroImpulse are doing a fantastic job making progress while balancing all the different opinions. It looks like this thread is progressing well, with feedback about what's not working with the current design informing future work. Thank you for keeping it civil.

Second, the biggest win in the recent redesigns is that it makes the styles of our different HTML assets similar, so now when you navigate between rust-lang.org, the standalone docs, and rustdocs, they don't all look completely different. It's not perfect yet, but it's better.

Keep moving forward.

brson commented 10 years ago

It's basically impossible to the requested revert at this stage. If there are issues with the current design please fix them.