Doc suggestion: Layout of Struct traits, methods, etc. vs Module traits, etc. · Issue #37856 · rust-lang/rust (original) (raw)

Doc Design Issue Thoughts

I've been looking into Rust a lot more lately after two false starts over the past couple of years, so I think I fit the pattern for a lot of people who are interested but are struggling to get over the hump of grokking Rust. One thing I've noticed and had "click" for me about the documentation that I find confusing is the difference between what's in the sidebar, and the user is actually searching for looking at. As an example, today I googled for the 'rust String doc' and was taken to this page.

I only just realized that everything on the left doesn't relate to the struct String at all. It relates to it's parent module std::string. If I want to see a list of functions String implements, I have to either scroll through the entire page, or hit the minus button in the upper right and scroll (which has pretty low discoverability, I only found out about it when trawling though an old thread on /r/rust. Perhaps it could be just the word "collapse" or "collapse all"? Digression, not what this issue is for).

If I want to see at a glance what traits are impl'd by String, this information also requires scrolling, and is interspersed by the actual methods on the trait themselves, so you can't see them all at once.

I would love to have the information for the Struct/Trait at hand more readily available for quick digestion, rather than that of its parent module. If I were looking at std::string, I would expect the information on the left of what you see in the linked image above to be front and center. And ta-da, it is ( after shrinking, while std is to the left, less distracting but there).

I suppose the idea of the current documentation is to mimic a sort of a hierarchical browser, and I do get it now. I just want to share that it was a source of confusion for me, where I would go to String docs, click on the Trait "ToString" to the left (a totally reasonable Trait to expect string to implement for itself in someway, just return itself), get confused about where I was and hit the back button. This would happen all the time. Now, looking back, I wonder how I couldn't understand, and so you all may think it's obvious as well, but I kept using the docs in a confusing fashion for a long time...

Additionally, c.f Ruby docs (which aren't that great really...) for which the left sidebar is not about the parent, but the current class

or Java, which has the same issue but makes it more clear via separation, and presents at the top all of the implemented interfaces/subclasses, before diving into the weeds further below.

Proposed solution

Make the sidebar to the left somehow more clear that it's unrelated to the main docs at hand for a Struct/Trait/Module. Perhaps a change in background color, or a stronger vertical divider. With a different background color (light gray, e.g.), the background color of the actually selected item (to return to the first example, the 4th item in the list of Structs, the red highlighted string) could remain the same color as the main page to clue the user that they're viewing a subset or lower level "window" into on part of the information presented on the left. Here's a quick example just by changing some CSS. I resized some things and changed padding to make the colors connect, but you can get the gist.

Present the summarized information for the Trait/Struct/Enum (e.g. for a struct, a list of impl'd traits and methods) either

in the right hand sidebar, always visible, that can be used to quickly access one in the main docs.
beneath the top level description, but above the detailed documentation contents as a sort of "table of contents" (like the Java doc), which can be used to quickly access each relevant piece without having to scroll.

I prefer the first of those two suggestions, if only because a) the space is available b) the second solution mimics just having the page load with everything folded up (save quickly view impl'd traits, which you can't do at all) and c) the information would be visible no matter what part of the specific documentation are being viewed. This is less easy to mockup just by modifying the page but I think that get's the idea across.

I'd be happy to look into doing this if people agreed with me that it would be valuable.