Open lambda opened 5 years ago
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.
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.
@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.
@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!
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.
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.
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.
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: https://github.com/rust-lang/rust/issues/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 https://github.com/rust-lang/rust/pull/86283, which I'd like to pick up and work on again soon.
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.
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.
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 [-]
.
I often use [-]
(mostly the global one) to go through items faster.
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.
So we need the [+]
but the local [-]
seem unnecessary.
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:
For comparison purposes, a quick survey of similar docs (whether in the standard library or a third party library) from other languages:
<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.[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.[+]
,[-]
, 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.<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:
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:
impl PartialOrd<Ipv4Addr> for IpAddr
should be shown on theIpv4Addr
page, but there's no need to show its methods, you could click through toPartialOrd
orIpAddr
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.impl PartialOrd<Ipv4Addr> for Ipv4Addr
andimpl 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 anIpv4Addr
, without being repetitive or requiring disclosure controls.[-]
adds extra noise once you're viewing it.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.