Proposal: largely revert the recent docs style changes #13780

Closed
chris-morgan opened this Issue Apr 26, 2014 · 29 comments

Comments

Projects
None yet
@chris-morgan
Member

chris-morgan commented Apr 26, 2014

#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”:

  • 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)—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

This comment has been minimized.

Show comment Hide comment
@chris-morgan

chris-morgan Apr 26, 2014

Member

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.

Member

chris-morgan commented Apr 26, 2014

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

This comment has been minimized.

Show comment Hide comment
@bachm

bachm Apr 26, 2014

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

bachm commented Apr 26, 2014

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

@liigo

This comment has been minimized.

Show comment Hide comment
@liigo

liigo Apr 26, 2014

Contributor

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

#12996 mozilla#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
.

Contributor

liigo commented Apr 26, 2014

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

#12996 mozilla#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

This comment has been minimized.

Show comment Hide comment
@Seldaek

Seldaek Apr 26, 2014

Contributor

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 :)

Contributor

Seldaek commented Apr 26, 2014

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

This comment has been minimized.

Show comment Hide comment
@vky

vky Apr 26, 2014

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.

vky commented Apr 26, 2014

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

This comment has been minimized.

Show comment Hide comment
@huonw

huonw Apr 27, 2014

Member

Some issues related to the fancy new fonts in the new style mozilla#13593 mozilla#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).

Member

huonw commented Apr 27, 2014

Some issues related to the fancy new fonts in the new style mozilla#13593 mozilla#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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 27, 2014

Contributor

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.

Contributor

adrientetar commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@huonw

huonw Apr 27, 2014

Member

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. :)

Member

huonw commented Apr 27, 2014

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. :)

@huonw huonw added the A-docs label Apr 27, 2014

@iliekturtles

This comment has been minimized.

Show comment Hide comment
@iliekturtles

iliekturtles Apr 27, 2014

Contributor

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.

Contributor

iliekturtles commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 27, 2014

Contributor

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.

Contributor

adrientetar commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@nham

nham Apr 27, 2014

Contributor

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.

Contributor

nham commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 27, 2014

Contributor

@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.

Contributor

adrientetar commented Apr 27, 2014

@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

This comment has been minimized.

Show comment Hide comment
@yuriks

yuriks Apr 27, 2014

Contributor

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.)

Contributor

yuriks commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@thehydroimpulse

thehydroimpulse Apr 27, 2014

Contributor

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.

Contributor

thehydroimpulse commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 27, 2014

Contributor

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

Contributor

adrientetar commented Apr 27, 2014

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

@alxgnon

This comment has been minimized.

Show comment Hide comment
@alxgnon

alxgnon Apr 27, 2014

Contributor

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.

Contributor

alxgnon commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 27, 2014

Contributor

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:

  • Changed font-size from 18px to 15px
  • Reintroduced gray background for code samples
  • Tightened up the margins

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

Contributor

adrientetar commented Apr 27, 2014

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:

  • Changed font-size from 18px to 15px
  • Reintroduced gray background for code samples
  • Tightened up the margins

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

@adrientetar

This comment has been minimized.

Show comment Hide comment
@yuriks

This comment has been minimized.

Show comment Hide comment
@yuriks

yuriks Apr 27, 2014

Contributor

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.

Contributor

yuriks commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 27, 2014

Contributor

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).

Contributor

adrientetar commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@yuriks

yuriks Apr 27, 2014

Contributor

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?

Contributor

yuriks commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 27, 2014

Contributor

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.

Contributor

adrientetar commented Apr 27, 2014

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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 27, 2014

Contributor

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

Contributor

adrientetar commented Apr 27, 2014

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

@nwin

This comment has been minimized.

Show comment Hide comment
@nwin

nwin Apr 27, 2014

Contributor

@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… :)

Contributor

nwin commented Apr 27, 2014

@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

This comment has been minimized.

Show comment Hide comment
@steveklabnik

steveklabnik Apr 27, 2014

Member

I actually like the new design a lot more. shrug

Member

steveklabnik commented Apr 27, 2014

I actually like the new design a lot more. shrug

@thehydroimpulse

This comment has been minimized.

Show comment Hide comment
@thehydroimpulse

thehydroimpulse Apr 27, 2014

Contributor

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:

  • Content is the #1 goal. You should be able to see the content extremely easily.
  • The breadcrumbs are out of the way. They are up top so that people can see and use them, but they're not in the content.
  • The sidebar is super light. No need for cluttering your vision because content is the focus. They don't make an emphasis on search, but search is still there and is useful.
  • The overall page is easy to take in. It's nice and white, standard page that doesn't need to be unique. That's not the goal of their doc site.

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.)

Contributor

thehydroimpulse commented Apr 27, 2014

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:

  • Content is the #1 goal. You should be able to see the content extremely easily.
  • The breadcrumbs are out of the way. They are up top so that people can see and use them, but they're not in the content.
  • The sidebar is super light. No need for cluttering your vision because content is the focus. They don't make an emphasis on search, but search is still there and is useful.
  • The overall page is easy to take in. It's nice and white, standard page that doesn't need to be unique. That's not the goal of their doc site.

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

This comment has been minimized.

Show comment Hide comment
@adrientetar

adrientetar Apr 28, 2014

Contributor

@yuriks Settled on 15.5px to workaround the issue.

Contributor

adrientetar commented Apr 28, 2014

@yuriks Settled on 15.5px to workaround the issue.

@brson

This comment has been minimized.

Show comment Hide comment
@brson

brson Apr 30, 2014

Contributor

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.

Contributor

brson commented Apr 30, 2014

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.

bors added a commit that referenced this issue Apr 30, 2014

auto merge of #13776 : adrientetar/rust/rustdoc-fix, r=brson
- Closes #13591. Relevant example: http://adrientetar.legtux.org/cached/rust-docs/struct.CChars.htm
(Had to use `!important` to override CSS selector precedence, namely matching over parent class.)
- Implement changes from #13780 feedback, namely:
  * Changed font-size from 18px to 15px
  * Reintroduced gray background for code samples
  * Tightened up the margins
- Fix point 1 and point 4 of #13804.

Samples:

- [enum.FileType](http://adrientetar.legtux.org/cached/rust-docs/enum.FileType.htm)
- [struct.CChars](http://adrientetar.legtux.org/cached/rust-docs/struct.CChars.htm)
- [std](http://adrientetar.legtux.org/cached/rust-docs/std.htm)
- [std::io](http://adrientetar.legtux.org/cached/rust-docs/io.htm).

r? @brson
@brson

This comment has been minimized.

Show comment Hide comment
@brson

brson Jun 19, 2014

Contributor

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

Contributor

brson commented Jun 19, 2014

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

@brson brson closed this Jun 19, 2014

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