Standard library documentation on doc.rust-lang.org hard to navigate

Is it me or is the docs site hard to navigate?

Half the time I don't know where I am (am I in a trait or a struct or somewhere else…) or where I can go from a given point. There seem to be lots of dead ends in the navigation, the sidebar seems to change as well.

I also don't really know on which package I am or which version (I occasionally end up on outdated documentation and then it's hard to get current) and there seem to be lots of hidden menus.

On mobile the navigation is even more bare and hard to use.

I don't know. Do people recognise this is an issue?

(Even if they do, I can't lead on fixing something of that magnitude so I hope somebody else could.)

I think being more specific will help in finding a fix for the problem you're facing. So instead of being like "Half the time I don't know where I am", tell us what are your navigation issues.
If you'd ask me, no I have no problem navigating or knowing where I am - which is why it isn't obvious to me what problem you are facing.
More descriptive text and perhaps screenshots would go a long way....

1 Like

I agree. I've been (trying) to learn how to navigate rustdoc for a couple of years and I also think it's hard.

I wouldn't be able to give specific improvement ideas other than "it's hard for me", because I'm not skilled in ux/ui design.

Some spontaneous things that I want to call out that are specifically hard (without specifying improvements):

  • Hierarchical navigation is really confusing in rustdoc
  • The layout of function documentation (both expanded and unexpanded) is very visually busy and makes it hard to focus/read.
  • For some reason e.g. attribute macros in the tracing crate don't show up in the navigation menu to the left, you have to find them linked in the root page text - but I don't know if this is generally true.

@RedDocMD I think it's perfectly fine starting a discussion around this subject with such a wide/unspecific question. Especially if it can lead to issues/RFCs to improve the situation.

The caveat here is that different ux/ui works well for different people, but there might be a way to change rustdoc to improve it for more people.

3 Likes

I think the question title and the question body are unrelated, though. The question body leads me to believe we're discussing rustdoc layout for any crate, but the title suggest the https://doc.rust-lang.org site is hard to read which I don't think is true/related.

I agree. I think rustdoc-generated documentation is just not meant to be browsed. It's optimized for looking up things via search.

1 Like

Might be related:

  • For "get me all info on struct XYZ", I find standard rust crate documentation to be quite helpful.

  • For "what structs should I care about", I find easier to jump around in IntelliJ

That was my question more or less:
Do other people have a similar feeling to me?
Are there any initiatives underway to do something about this?

I could pinpoint exactly the points and areas where I think there is an issue and make a detailed usability review but I don't have that much time and I'm not sure whether it would be useful to dump something like that on the forum here.

What would be a possible constructive course of action here? From experience in other languages (cough Python) I know how underowned and unloved the whole documentation website can be.

3 Likes

I just had the same issue when reading this topic's original post. The doc.rust-lang.org domain includes lots of other things, in particular all the books (the book, reference, nomicon, rust by example, cargo book, rustdoc book, etc, etc). I've adjusted the title accordingly to specify that this is about standard library documentation only.

Well, no… oh. Crates have the same layout but are on a different domain?

Unrelated, but here's a nice one from the pathfinding crate, got bitten by this a couple of times:

There's a Dijkstra algorithm in this crate. I want to get at it. I press Dijkstra and that sends me offsite!

Finding the actual Dijkstra algorithm, god knows. Is it under Modules? Oh there's a Modules link in the left sidebar and a Modules section of the same name.

I press "directed" and there it is, but now the sidebar changes and I have no way of getting back up again in the navigation. The only thing I can do here is press browser Back.

Or I get back to the Crate home by pressing the Rust icon? Super weird.

Well, of course most of your observations will apply do anything rustdoc generated in general. But you probably weren't complaining about navigating e.g. the book, which - under the docs.rust-lang.org domain - leaves only the standard library docs (and maybe also the internal compiler API docs).

All crates.io crates get generated documentation on docs.rs, which does not share some of the problems you described, in particular

this is addressed by an additional bar on top so that e.g. on some page like https://docs.rs/tokio/1.14.0/tokio/io/trait.AsyncRead.html, you'll still see the version of the crate on top, along with an orange ":warning: Go to latest version" button when you're not at the latest version. Whereas for the standard library, the only way to know you're seeing an outdated version is to spot the missing stable or nightly in the URL.

1 Like

In this case, using the search bar helps. Or you can look at the modules not in the sidebar but further down under "Modules", where you can also see their description.

You can, at the top of the page where it says "Module pathfinding::directed::dijkstra", actually click on every component of that path to get to any higher levels in the module structure.


The sitebar is, on any page, an abbreviation / overview of the contents of the module/trait/type whose documentation you're currently viewing.

1 Like

I mean sure I could learn to use the site but these issues will be there for everybody who's new (and I'm not exactly new anymore).

I never use the sidebar. I pretty much always navigate by the search bar in the top, and when I don't, I'm clicking links on the actual page, and not the sidebar.

3 Likes

I would love to see that line pinned on top of the page and not to scroll away.

When I was still new to it, I was very confused by the rustdoc-created docs. I got used to it. When I showed some documentation to a colleague (who is not programming Rust), he found the presentation style horrible. I learned to like the way it works (particularly the search works very well!). I'm sure it could be improved, though.

1 Like

I also grew used to rustdoc.

What I've come to appreciate over most other languages is how standard rustdoc makes documentation accross the Rust ecosystem.

Every Rust crates share the same basic layout. With a set of good shortcuts, easy search, every keywords being links.

If I want the doc of the foo crate version 1.2 I can type docs.rs/foo/1.2 directly.

I work almost exclusively with JaveScript at my current day work, and I feel that lack of standardization every time I have to look something up.

1 Like

I agree, use the search. I find the side bar annoying when I ctrl-f (Find in This Page) search a page for text.

If you know you’re searching for something contained in the current module/trait/struct, on a page like this you can search for e.g. "fn map" instead of "map", to quickly find the item, and match nothing on the sidebar. The same trick is also incredibly useful when using ctrl+F on Rust source code. On the other hand, if I would search for a method with e.g. map anywhere in its name, I would only scroll through the sidebar and rely on the results being highlighted; so it can be quite useful to have results in the sidebar.


But I'd be interested to hear about a concrete scenario where the sidebar hinders your ctrl+F search.

1 Like

Just annoying. Not a concrete problem. For example I am a permanent beginner. If I am reading the std::vec::Vec page it is quite long and I am trying to understand it. So as the page is long and by the time I get done with a few scrolls I start to forget what I read before and so I search for a word and off to the side I go.

Indeed. It's like the infamous gofmt's style is nobody's favourite, but gofmt is everybody's favourite.

Same with Rust documentation: perhaps it's possible to make some part of it better (for some definition of better), but I would hate to see different crates trying to do that individually and turning Rust documentation into zoo of different styles.

Changes to rustdoc are more of IRLO material not URLO which high chance of getting answer well, it's not perfect but people already know how to deal with it, it's not clear if UI experiments may improve usability enough to warrant radical changes.

Small, focused, suggestions may be accepted, of course.