Lately I've been thinking about how rustdoc could be improved to make it easier to use. As an exercism mentor, I often hear people complain that the documentation looks confusing, and that it's difficult to find information.
Here are some problems I identified:
When using the documentation for the first time, there is an overwhelming amount of information.
There is a lot of visual clutter.
There is little spacing between elements; items aren't clearly separated.
The sidebar is supposed to provide an overview, like a table of contents. However, it is often very long, so it's tedious to scroll through it to find something.
Many items, e.g. methods, are expanded by default. This is great when reading a page from top to bottom, but that's not how documentation is usually read.
You can press the - key or click the [+] in the top right corner twice to collapse everything, but not everybody knows that.
Not all functionality is self-explanatory, for example the [+] button in the top right corner, the theme picker or the settings button.
It's also not obvious that some items (e.g. types, traits, and the buttons with square brackets) are clickable.
Here are some ideas I came up with to improve it:
More items, e.g. functions/methods, should be collapsed by default.
Some buttons, e.g. [+], [-], [src] should be hidden and only appear when the item is hovered.
Links in the Rust code should be underlined when hovered
When hovering an item, its background color should change
Square brackets of buttons should be replaced with a border
Sections in the sidebar should be collapsable, and most of them should be collapsed by default
The sidebar could be made bigger
I implemented the collapsible sidebar with a userscript. I also made the headings sticky, i.e. they stay at the top when scrolling over them; this is supported by all major browsers and requires no javascript:
This is currently implemented in an (unpublished) greasemonkey script, because it was much easier this way, but I'd like to implement it in rustdoc directly.
This could even be implemented without JS, using the <details> and <summary> tags.
What do you think about this? Do you have more ideas?
But since you’re focused on visual stuff here, I’d like to mention a visual problem, too: long impl blocks are terrible. You never know the constraints on the type variables because the block begins off-screen, and even scrolling up is to where the block begins is super hard since it is impossible to tell at a glance where the impl begins. Perhaps something like sticky headings would work on impl blocks, too.
I'm really not a fan of hiding parts of the interface, especially behind hover. Personally I find it hard to use and discover buttons that are sometimes there sometimes not, especially when it depends on where you happen to position the mouse pointer at any given time. And of course "hover" assumes I'm using a mouse which may not be true.
Good point! Of course the buttons should also appear when the item contains the keyboard focus, and they should be always visible on smartphones.
When most items are collapsed initially and the screen is full with methods or impls, it's not hard to discover that hovering an item reveals additional buttons
On another note, the page could be more keyboard accessible
I'd go even further and punt all deprecated items at the bottom of their respective list. People shouldn't see deprecated items unless they're ctrl+f-ing for them.
Have fewer different colors. The current formatting is a riot of color, which imitates the look of an IDE, but the constraints of an IDE are different from the constraints of a web page, where an excess of color makes it harder to spot important elements. Overall, I'd go for for a two-colors design: non-clickable and clickable text. Which brings me to...
Make fewer things clickable. If the doc needs an anchor link for a method, it's probably better to have an anchor character than to make the entire method name clickable. Similarly, basic primitives like bool or i32 probably don't need to be links. I'd say even associated Self types don't need to be links (they're easy to find), but that might be a bit too far.
Trim extra keywords. The initial text for a given function should be fn function_name(args) -> ReturnType, nothing more. Attribute keywords like pub, const, unsafe and the like are important, but they're less important than the function name, so they should not clutter the area where it's expected. I recommend putting them in the top-right instead.
Make titles more distinctive: All titles, including section names, function names and sub-section names should be made bigger, and underlined if they aren't already. In particular, it's a little confusing that sub-section names (the blue ones) are more distinctive than function names.
I think the rustdoc team would be well-served to take inspiration from eg the Qt doc. The doc as it is tries too hard to imitate / reuse the syntax and look of Rust code, even in cases where it's detrimental to visibility.
I highly disagree. I really like to be able to immediately tell the difference between functions, types, and trait without having to read the whole context.
I don't think it's a good idea. Being able to click on any types (including the primitives ones), functions and traits is a something that make rustdoc very usable for me. Given that even primitives types implements traits (and so can have many "methods"), I don't thing that hiding (which is what removing hyperlink is) that information is something we want.
Good idea. I like the idea of de-clutering the main space by moving secondary items elsewhere.
I really like the overide/protected/virtual in a separate space, where it doesn't add clutter.
However I find it much less readable than the current output of rustdoc because of the lack of semantic in (and lack thereof) coloration. I can scan the output of rustdoc, while I need to read the Qt doc, which means that when I need to search something visually I am much, much slower.
All this emphasis on color-coding, such as the first and last segments of the above reply, makes me wonder how accessible rustdoc is for people with different forms of color-blindness or low vision (or simply blind). That is primarily a problem for male readers since, IIRC, 4% of males of northern European descent are red-green colorblind.
Using ONLY color to convey semantic information is definitely a no-no; however, using it to draw attention to semantics made already clear in the absence of color is OK. The best solution would be to provide an option/preference for the page of whether to use color to highlight semantics or not. The page must be entirely usable and all information still available with the option turned off. This helps everyone, including those requiring accommodation.
rustdoc has been checked for color-blind accessibility and there was a design pass around it. Particularly, it avoids using colors that just use one channel, like pure red, green, blue, so that lack of one channel doesn't make text vanish. You can trial that effect using a simulator, there's a number of browser addons that simulate color-blindness of multiple varieties. If you use one of them, you will notice that colors lose brilliance and pop out less, but don't fade out.
One thing brought up recently on URLO was that, without scrolling, it's not trivial to see if a method is an inherent method, a method available via deref coercion, or via a trait.
As I pointed out, a small CSS snippet would mostly suffice by ensuring the header is always visible.
While not trivial, it is possible to work around this using some JavaScript. I know I've done it before, though I'd have to dig to see if I still have the code.
