Rustdoc formatting presents accessibility issues

[lambda]

In a thread on Reddit about finding Rust's documentation hard to read, one user pointed out that it's especially bad for people with dyslexia.

Not having dyslexia myself, I did a little bit of research on UX design for dyslexia. One resource I found pretty good was this article, and in particular the presentations at the end.

One of the points about design for dyslexia, which can even help for those who are not dyslexic, is reducing the amount of visual noise and clutter. A quick pass shows that there are a lot of noisy elements. Most of them exist for a reason, but I'm not sure all of those reasons fully justify the amount of noise. I have highlighted a lot of the things that catch my attention which are not content.

There are a lot of different colors used on the page. Blue is used as the standard link color; but links to other items in declarations also use a custom color scheme for different types of items, like primitives vs. structs vs. enums vs. type aliases. I don't know about other experienced Rustaceans, but as an experienced Rustacean myself, I certainly couldn't tell you what color corresponded to what kind of type it is; but rather, as an experienced Rustacean, for most of those types I either know what it is, due to familiarity with the type or familiarity with conventions, or I don't really need to know what it is and can click through to find out if I want to.

Then the example code is syntax highlighted using a different scheme than the declarations. Again, syntax highlighting has some value for readability, though I find some aspects of syntax highlighting to be more helpful for writing code than reading it. I would be interested in hearing about usability studies on readability of code based on various syntax highlighting schemes; my guess would be that some aspects of highlighting, like longer spans of text which may be commented or quoted, would be more helpful for reading than others that are already locally obvious enough in the bare syntax. Anyhow, syntax highlighting may or may not be unnecessary noise, but in conjunction with the other highlighting scheme for declarations, there's definitely some room for improvement and simplification.

There are a lot of UI elements all over the page. The search box, which contains a lot of text with instructions, the theme chooser, the settings, all of the little disclosure [+] and [-] controls. Many of these seem to have good intention, but they add up to a lot of extra clutter. The disclosure boxes in particular are trying to balance between having complete information on the page and having too much extra information due to implementation of common traits with repetitive docs, but in doing so, they add a lot of extra noise to the page themselves, and make it a lot more work under the default settings to dig in and see everything implemented for a type.

There are also a couple of distracting design elements, like all of the horizontal rules. Most of them are in places where there is already some other visual element distinguishing sections, such as headers and spacing; they could probably be dropped with no ill effect. Another is the use of a grey background for <code> and <pre> elements; while this can help distinguish code from the surrounding text (especially when it is something like a single character which may be hard to distinguish by font), and is fairly common in a lot of places that support embedded code like GitHub, StackOverflow, and various other languages documentation, it does add some more noise and draws attention, so it should be carefully considered whether it is worthwhile.

While a lot of these design elements are there for a reason, the overall effect is somewhat reminiscent of the "chartjunk" which cropped up in the Excel era:

As a contrast, I took a screenshot of similar information from godoc.org, a Go documentation hosting site similar to docs.rs. There are many fewer elements I could identify as noise or clutter:

This is not quite fair, as the Go docs have one page per module rather than per type, so we don't see all of the navigation elements, but even if you scroll up to the top, you will see that the navigation elements are much simpler, with less on screen at once.

Beside the visual clutter, there are a few other aspects of the default Rust docs styles which can cause problems for people with dyslexia:

• It uses serif fonts for the body text, while sans serif fonts are generally preferred for readability
• It has very long line lengths; I counted 127 characters on a line, which is above a recommended 100 characters max for online use, 65 for being more comfortable for the average adult, or 45 for being best for those with dyslexia
• The default light theme is high-contrast, black text on a white background, which can be difficult for some people to read. The dark theme is lower contrast, but not everyone prefers a dark theme.

For comparison purposes, a quick survey of similar docs (whether in the standard library or a third party library) from other languages:

• Python has a similar overall layout with some search and nav at the top, a nav bar to the left, and the content. The search and header doesn't seem as visually dominating as the search bar in Rustdoc. It has one horizontal rule. It takes an interesting approach to highlighting of inline <code>; they only use a grey background box if it is not a link, while the ones which are links (references to various functions and types) are only highlighted in blue. This does a good job of keeping the clutter down while still making all of the text distinguishable. It has one source link at the top, which uses the English phrase "Source code" rather than the abbreviation "src". Has English language compatibility information "New in version 3.3" at end of introduction. It has no disclosure boxes. It uses sans-serif fonts. An arbitrary line I picked was 103 characters long. High contrast black on white.
• Ruby also has a similar layout. Like Python, the header bar and search don't dominate as much as they do in Rustdoc. There is more noise overall than Python; very bright syntax highlighting, heavyweight boxes, but it still feels less cluttered than Rustdoc, without the disclosure controls, horizontal rules, [src] links all over, and highlighted method signatures. Hovering over method declaration shows that you can click to reveal source; slightly less discoverable, but also avoids extra noise when just reading. Serif font. Arbitrary line I picked was 77 characters long. High contrast black on white.
• Golang official site. Just header and content. Index is inline rather than in sidebar, with quick link to jump to index. Disclosure triangles only for overview and index, plus hidden by default examples. No horizontal rules, but headings do have heavyweight backgrounds. No styling for inline code. Headings for types and methods themselves are source links; somewhat hard to discover, but avoids visual noise. Sans-serif font. Arbitrary line I picked was 119 characters. Godoc site is very similar, but slightly different styling; smaller font, but narrower column means the same line wraps at 114 characters. High contrast black on white.
• Haskell has some similar issues to deal with as Rust, given the similarity between typeclasses and traits. It has a very lightweight header, a table of contents on the right side, a lot of boxes on the screen, a lot of disclosure controls and source links. It is one of the more visually noisy designs, although the disclosure controls and source links don't seem to be as distracting as the ones in Rustdoc as they don't look as much like some piece of syntax ([+], [-], and [src] all look like they could be some kind of syntax). Docs that describe something particular about a given implementation of a typeclass are displayed by default, but methods on typeclasses are not displayed without manually exposing them. No background boxes for inline code. Sans serif font. Very long line lengths; none of the docs were even long enough to wrap on my screen. High contrast black on white.
• Ocaml (this is not an official docs site or even a docs aggregator, so styling may be idiosyncratic). Extremely lightweight navigation. Just a couple of horizontal rules at the top. Extremely lightweight styling makes it somewhat hard to visually distinguish declarations from descriptive text. No disclosure controls, no source links. Sans serif fonts. Arbitrary line is 95 characters. Cream colored background provides slightly lower contrast.
• C#. Large, complex navigation header, and left nav bar, but all elements are visually less prominent than the header of the main content. Simple search box in nav bar. Somewhat visually heavy example code sections. No source links, nothing collapsible. Have to click through for full docs on actual methods. Sans serif fonts. Arbitrary line is 101 characters. High contrast black on white; has a slightly lower contrast dark mode.
• The Rust Book, using mdBook. This is actually used for other official parts of the Rust documentation, so is worth comparing and possibly emulating for consistency sake, though as a book and not automatically generated documentation it's not perfectly comparable. It has a very lightweight header, with a few small low-contrast icons for control, and the title of the book. It uses a single, very light, low-contrast horizontal rule to distinguish the header which is attached to the viewport from the text. You can collapse the navigation sidebar. Search requires clicking an icon, a search box is not shown by default. The heading for a chapter is much larger and more prominent than anything in the navigation bar. It has somewhat high-contrast, prominent icons in code samples, including "Copy", "Run", and "Show Hidden Code" depending on the sample; these can be a bit distracting. It uses grey background boxes for <code> and <pre>. The only disclosure controls are for hidden lines in sample code, and the sidebar. Trailing whitespace is used well to delimit sections. An arbitrary line is 102 characters. High contrast black on white; has several themes, including several lower contrast darker theme and one lower contrast black on beige theme, with a light on dark sidebar. The lower contrast theme also makes the icons in code samples quite low contrast, which helps make them less distracting, though it actually increases the contrast of the header icons, and the colors in the sidebar are somewhat bold and distracting. Has a print mode that allows loading the whole book at once for easier scrolling or browser search.

A few overall trends I note after looking at a lot of these:

• Every other site with both a header and a sidebar has the header span the whole page, rather than the sidebar spanning the whole page and the header being within the content area delimited by the sidebar. This seems to help with visually distinguish the header from the actual content of the page. Additionally, the other sites generally have a larger difference in size between the search and settings headers and the main content heading, making the main content heading more prominent; Rust's search bar is quite large, contains a lot of text, and the main heading is not much bigger.
• Only Haskell and Golang do significant amounts of hiding and disclosure. Golang hides examples by default, Haskell hides typeclass details by default.
• No other docs I looked at highlight different kinds of types differently.
• Most use sans-serif fonts and shorter line lengths than Rustdoc.
• None use horizontal rules as heavily as Rustdoc.

Some concrete recommendations based on the above. Most of these should be applied to all styles, but some may be appropriate for a special "readability" style. I'm sure not everyone will agree with all of these, but I think a lot of them are pretty universal usability improvements:

• Controls and search in Rustdoc header are visually distracting #59840 Make the search and settings less visually prominent relative to the main content
• rustdoc styling improvements for readability #59845 rustdoc styling improvements for readability
• Reduce visual prominence of controls, source links, and version numbers in rustdoc #59851 Reduce visual prominence of controls, source links, and version numbers in rustdoc
• Hide unstable items by default in stable rustdoc #59853 Hide unstable items by default in stable rustdoc
• Simplify and unify rustdoc sidebar styles #59860 Simplify and unify rustdoc sidebar styles
• Not everything present in the content is accessible from the side bar index (constants, impls on other types referencing this one). If everything were listed in the side bar index, that would make navigation easier and further reduce the need for disclosure controls in the body.
• Have fewer or no disclosure controls. Make decisions about what should be displayed vs. what needs to be clicked through to, don't make the user make that decision. This is probably the most complex part of these recommendations and may be appropriate to split into a separate ticket or RFC.
  • Any method that could be called on an object of the type or trait in question, or associated type, constant, etc, should probably be displayed with the summary line from the docs
  • Those things which indicate an implementation that references the item in question can be left with just the basic declaration information, since you should be able to click through to the type or trait documentation to get the full details
    • For example, in the "Implementors" section of a trait, there's no reason that you would want to expand to see the declarations of each method that you've already read in the trait definition. All you need to see are the declarations, and if you want you can click through to those types to see any details about their particular implementation.
    • In documentation for a type, impls for other types which just reference this type should be listed, but there's no reason to list all methods. For example, impl PartialOrd<Ipv4Addr> for IpAddr should be shown on the Ipv4Addr page, but there's no need to show its methods, you could click through to PartialOrd or IpAddr for that. What you want to see when looking at the docs for a given type are "what can I call on this type," while impls that merely reference this type should be linked but don't need methods expanded out here.
  • If there are multiple impls that apply to a type being documented, such as impl PartialOrd<Ipv4Addr> for Ipv4Addr and impl PartialOrd<IpAddr> for Ipv4Addr, all of the declarations (including type parameters and associated types) can be listed in a block, followed by one set of declarations and docs for the actual methods. This may be somewhat complex to specify and implement, but if done correctly would give just the right amount of detail to see everything you could call on an Ipv4Addr, without being repetitive or requiring disclosure controls.
  • Show the declaration of items by default. It can be after the summary; for traits, that would essentially provide an index of the methods.
  • Either always show attributes, or mark some attributes to always be hidden and let others always be shown. Most items with attributes only have one line worth of attributes, which makes the "Expand attributes" disclosure just as noisy as displaying the attribute itself, and then the [-] adds extra noise once you're viewing it.
  • I haven't been able to figure out the logic behind the "Show hidden undocumented items" disclosure when looking at trait implementations for types, which seems to show documented items. It seems that maybe it's hiding the mandatory to implement methods from which the default impls for the other methods can be derived? Either way, it seems like this kind of hiding isn't necessary if the other suggestions are implemented.

That came out longer than I originally intended, and some of these suggestions may be more debatable than others. If anyone would prefer I turn some or all of this into an RFC, I'd be happy to do that; but if an issue is an appropriate place for this, then we can leave this here.

[JayKickliter]

I'm the one who brought up the difficulty of reading rust docs with dyslexia on Reddit. Thanks so much for doing all this legwork. I'll read through your points and see if I can offer any more input/validation. I would love to hear from other Rust developers with reading difficulties since dyslexia isn't as well defined as most people think.

[euclio]

I think it would be helpful to revisit some of the UI in terms of colorblindness as well. The search page in particular is hard for me to use. It distinguishes macros, functions, etc. by color. If I'm searching something that exists in multiple namespaces, it's difficult for me to distinguish what item I actually want.

[lambda]

@JayKickliter Unfortunately, I tend to be a bit verbose in my write up, which I'm sure doesn't help your read through. If I were faster and better with graphical mockups that would probably be easier for you to review.

[skade]

@euclio I know that there was a pass for choosing the type colors with color-blindness before 1.0, but we couldn't get as much feedback back then. The search module is indeed problematic! It would be great to open another issue around that subject!

[skade]

Reading through this, I feel like this issue could use some splitting up. It's a great writeup, but way to much to turn into an actionable issue. That would then allow to make gradual changes with immediate impact.

For example, I disagree that the global search bar is too dominant. I use it a lot for discovery and I know a lot of my trainees like it, too. I just don't feel it lives up the potential. (This is actually an area of expertise I have, I develop and build search functionality) That would itself merit a complete issue.

[lambda]

Yes, this could definitely be split up into a number of smaller issues. I created the checklist as a start, but I can start splitting off some of those items and groups of items into separate issues.

And many of these points are definitely open to debate. Just doing a quick glance at a page, the search and controls at the top definitely feel fairly heavy weight. However, I also find that I use the search on Rustdoc more than I do on other docs; for instance, Python is the main language I use in my day job, but I use Google search rather than Python's doc search. So yes, I see the value in the discoverability.

But the prominence of the top header is not just due to the search bar, but also the other controls, which have high-contrast icons, with individual boxes around them, which are not sized similarly to the search bar, plus a horizontal rule that spans only some of the elements, so the whole thing makes a non-rectangular shape that stands out.

Anyhow, as mentioned, it would probably be worthwhile to break down into other issues. I'll start to group the suggestions I provided and break out related groups of suggestions into separate issues.

And yeah, I didn't even start to address the search page itself in this writeup. I have several thoughts on that, plus there's the colorblindness issue mentioned, but felt like there was more than enough to discuss on the content pages that the search page would be a whole different discussion.

[Aloso]

I am slightly nearsighted, so I would prefer a larger font. By zooming into the page, the content becomes wider, which is suboptimal.

Reducing contrast is not a good idea, contrast is important for legibility. We could provide a third theme with less contrast, but that should be turned off by default.

I agree that we can reduce visual clutter – especially dark lines and borders in the sidebar. The [+] and [-] buttons should have proper borders instead of brackets. Also, the [-] should be hidden until you hover over an item.

We can also make the page clearer by reducing information. For example, blanket implementations could be collapsed by default. Some lifetimes could be hidden (this should be configurable). The pub in method declarations is unnecessary.

[jsha]

Thanks for writing all this up!

There are also a couple of distracting design elements, like all of the horizontal rules. Most of them are in places where there is already some other visual element distinguishing sections, such as headers and spacing; they could probably be dropped with no ill effect.

The excessive horizontal lines is now fixed: #90033. We still have horizontal lines separating headings in the top-doc, and separating major sections like "Implementations." In my opinion those are still useful.

Also, the [-] should be hidden until you hover over an item.
The pub in method declarations is unnecessary.

I very much agree. I incorporated these two changes into #86283, which I'd like to pick up and work on again soon.

[camelid]

Also, the [-] should be hidden until you hover over an item.

The issue I see with this is that it will cause controls to appear and disappear as you move your cursor around the page, which seems like it'd be distracting. Also, hover-based controls won't work on mobile.

[jsha]

Yes. The implementation I proposed on #86283 did not rely on hover. Instead, I proposed that we should only show [+] by default. The [-] would only show up when you've expanded a section and might want to collapse it again. The intuition here is that people don't usually close individual sections - they expand individual sections, and they collapse all sections using either the top toggle or the +/- keyboard shortcut.

[camelid]

When are the situations that people collapse docs? If it's to get a high-level overview of all the impls, then I wonder if we could make the improvements to impls in the sidebar and get rid of most of the toggles. FWIW, I almost never use [-].

[GuillaumeGomez]

I often use [-] (mostly the global one) to go through items faster.

[jsha]

I also occasionally use the global [-], but never the per-item [-]. I use it to skim methods including their parameters and return type, which the sidebar can't show.

[GuillaumeGomez]

So we need the [+] but the local [-] seem unnecessary.