Reduce visual prominence of controls, source links, and version numbers in rustdoc

[lambda]

This is being broken out of #59829 to provide smaller, actionable items that can be independently discussed and worked on.

A review of rustdoc for accessibility, especially for dyslexia and attention disorders, finds that there are a number of visually distracting elements in rustdoc which can draw attention away from the main content. These should be considered along with the other issues mentioned in #59829 about the overall effect of a number of distracting elements on the page.

Items in rustdoc can have a number of controls and auxiliary information associated with them, which can be quite prominent and distracting. These should either be eliminated, or made less prominent so that the reader can more easily follow the main content and only notice them when they need to find them.

At the top of a page, we see several controls that are larger and more prominent than the main text. The top of page [-] and [src] controls are larger and bolder than the body text. The version number is a bit smaller and lower contrast, but unexplained what it means.

Immediately above the main text is a "Show declaration" disclosure which is lower contrast, but larger, than the main text, and the main text itself also has a disclosure control immediately to its left, crowding it.

impl blocks have disclosure controls indicating a nesting relationship, even though the headings themselves don't, which leads to some distracting spacing. They also can have a number of closely spaced prominent [src] links and version numbers. The [src] links are a slightly larger font size (17px) than the content (16px).

There are also a variety of different sizes of these disclosure controls, which don't match the logical hierarchy.

There's an additional "important traits" control that appears on some methods which indicates some important traits implemented by the return value of the method. This allows showing traits that are implemented by the return type for thing like iterator adapters, where the user usually cares more about the trait implemented than the concrete type. This adds another UI element which is high contrast, doesn't match in size, and has a different way of disclosing hidden information. Previous discussion of this design is present in the implementation issue, #45039.

There is going to need to be a balance between reducing or eliminating the visual impact of these elements, while still making the same information easily discoverable for those who need it.

Here are a few suggestions about how we might be able to achieve this.

• Avoid having these elements look like syntax. [+], [-], and [src] could be mistaken for some kind of source code annotation; the brackets are also very eye-catcing. Using more standard disclosure controls (such as ⊞ and ⊟, or ▶︎ and ▼), and prose like source instead of [src], may help.
• Make source links and version information smaller and lower contrast; could make them become full contrast on hover
• Move version numbers introduced and source link to less prominent location
  • perhaps inline with the text of the docs
  • perhaps immediately to the right of the first line of the declaration, rather than right-justified
• Use English for the version number and source link
  • "Introduced in Rust 1.12.0"
  • "Since 1.12.0"
  • "source"
  • Something simple like "(since 1.12.0 / source)" might be appropriate.
• Adjust the sizes of disclosure controls and text to follow logical hierarchy and be smaller and less prominent than content
• Use standard disclosure control for "important traits", or if possible, just include the relevant information inline so you don't have to click through to it. These options were considered but ultimately not chosen in the implementation issue show in docs whether the return type of a function impls Iterator/Read/Write #45039.

[the8472]

Only show some or all of these elements if items are being hovered over

Hover is not necessarily obvious on touch devices.

perhaps immediately to the right of the first line of the declaration, rather than right-justified

Javadocs put this information at the bottom of descriptions as documentation-annotations.

[lambda]

Hover is not necessarily obvious on touch devices.

Good point. I'll modify the suggestion about hover to only have it change contrast rather than displaying items.

Javadocs put this information at the bottom of descriptions as documentation-annotations.

Yep. Python also puts them in the description (though its docs are written manually, not generated by a doc generator). cppreference (also manually written, not automatically generated) puts them next to the name of the item in question in tables of contents, and next to the declaration on the details page. Many others I've looked at don't include this information in an easily accessible manner, as far as I can tell. I do appreciate that rustdoc tries hard to report version availability, though it's missing on a lot of items, but I think it gets slightly more prominence than it should.

[Centril]

This seems like it is mostly a workaround for the fact that many interfaces were stabilized before impl Trait existed, which means that there are concrete types being returned when what the user of the interface is interested in is the trait implemented by the return value.

No, that's not why. We still don't use -> impl Trait for e.g. Iterator even when we can. Due to conditional implementations, -> impl Trait can eliminate capabilities that you'd otherwise have. For example, we have impl<I: Clone, F: Clone> Clone for Map<I, F> but if you return -> impl Iterator<...> then the compiler doesn't know that.

[lambda]

@Centril Thanks for the correction, updated to hopefully be more accurate.

[ghost]

Here's a quick mockup of what this might possibly look like:

The body font I've used is Source Sans Pro which complements the Source Code Pro that the docs are already using for code blocks.

The length of paragraphs and list items is limited separately from code blocks and headings, I feel that this provides an optimal experience especially when dealing with computer generated content like the main content heading.

The "Show Declaration" box has been styled as though it was content, and when collapsed shows the type and name but no fields that are defined.

I also moved all of the collapse toggles and header links into the far left column for the sake of consistency.

[the8472]

Using more standard disclosure controls (such as ⊞ and ⊟, or ▶︎ and ▼), and prose like source instead of [src], may help.

Would it make sense to switch to <details>?

[lambda]

@measlytwerp Thanks for putting that together! I like the mockup a lot; it addresses may of my points. It does still have the [src] on the right for the traits, but it looks like a big improvement.

[lambda]

Would it make sense to switch to <details>?

You could switch to using <details> here, but you'd still need to customize the styling because the browser default style might be a little too heavy. I think whether you switch to <details> is more of an implementation issue, and question of accessibility to screen readers, which should also be considered but I have nowhere near the expertise to comment on that.

[lambda]

Review of specific thoughts on @measlytwerp's mockup:

• The main heading stands out better with less clutter around it
• The stability and source code links being in prose and inline looks good
• I love showing the abbreviated declaration instead of "Show declaration;" that's a great touch
• The disclosure controls are less distracting here, especially now that they line up
• The sans-serif body font looks good
• The shorter lines look good and look like they'll be more readable, though a page with longer text would help compare better
• The shorter lines do lead to some extra whitespace on the right. That could be OK, except the width of the search bar and the the [src] link makes it feel a bit unbalanced. Moving the rest of the [src] links inline and making the search bar width match the new narrower content could help.
• Losing the backgrounds on the <code> definitely helps out a lot with the clutter
• This does drop the feature of a "run" button for the examples. I've always liked that the docs give you the ability to run the examples in the playground, though I hardly ever use it. I think for the purpose of this ticket, we should probably try to maintain functional parity, and consider the tradeoffs for that functionality in other tickets. I wonder if this would work well as just a prose link like "Run" either before or after the example, similar to making the "Source Code" link an inline link. Or maybe put it on the top left, in a background color that matches the grey bar on the side, to make a little corner around the example, with the run control in the top portion of the corner.
• I wonder if the § symbol is really necessary to the left of the headings, or if it could just show up on hover like it does now. The headings are already a clickable target
• And as mentioned, I think that the [src] link at the bottom could also be put inline and in prose like the one at the top.

Overall, really like the mockup; I think it addresses a lot of the issues, and really looks like a big improvement. Thanks @measlytwerp for doing that!

Any chance it could be turned into something that could be browsed live to see how it works on more docs?

[ghost]

I think the only practical way to do that would be to do the work and modify rustdoc as there were a lot of underlying markup changes I had to make in order to get the styling to be reasonable.

I'll make a start on it now.

[ghost]

One question that I don't see a clear answer to, what browser compatibility are we looking for? I see that there's currently a message in the docs about IE8 not being supported, but what about IE9 and 10?

Edge, Chrome, Safari and Firefox shouldn't be a concern.

[lambda]

I don't know if there's a specific policy, but Rust offers Tier 1 support for Windows 7 and up, and IE 11 is the latest browser available for Windows 7. Based on global usage share numbers, I doubt that there's much of a call for earlier versions of IE especially among a technically oriented crowd, but I think that targeting IE 11 is probably a good idea unless there's a good reason not to.

[ghost]

Yeah IE11 is fine.

I'll try and put what I've done so far up before I sleep tonight.

[ghost]

Here's my working branch, and I've also made a GitHub pages site out of the docs.

• Its currently quite broken
• Many things are disabled or just not styled
• Source Sans Pro and Source Code Pro have not been bundled

I'll continue working on this tomorrow.

1: https://github.com/measlytwerp/rust/tree/rustdoc-reskin
2: https://measlytwerp.github.io/rustdoc-reskin/std/

[ghost]

Interesting, our earlier discussions are currently dated as being in the future. I thought GitHub had swallowed my post.

[lambda]

Ooh, wow, the timestamps are off. And they were off in the other direction when I checked earlier today; shortly after posting the exchange about IE, they were dated 5-8 hours ago, now some are in the future. GitHub seems to be having some issues.

https://twitter.com/githubstatus/status/1126171459255185414

Took a quick look and I like the start. Definitely a lot of rough edges, but it looks a lot cleaner already.

[ghost]

I've gotten quite a bit more done today.

• Standardised html being generated pretty much everywhere
• Styled the header/search bar
• Added 'Night Mode'/Dark Theme
• Added larger fonts mode

You'll notice in particular that there's now a line drawn along the side of the screen marking where collapsible sections start and end, it's very faint so as to not interfere with reading. I've done this because I kept getting lost when collapsing things because without nesting there's no way to know when something ends.

Another thing of note is that headers in markdown or generated by the docs are no longer linked. The headers next to collapsible controls were linked, which was very confusing. Instead I've added a # link after each header.

The rustdoc code is quite a mess, but I'll continue tomorrow.

https://measlytwerp.github.io/rustdoc-reskin/std/

[ghost]

Got a lot more small bits finished today, things are looking a lot nicer.

It'd be good to get some feedback on this work, I've had some elsewhere that's been mostly positive, but constructive criticism is wanted.

https://measlytwerp.github.io/rustdoc-reskin/std/