Rust has a documentation discovery problem

there's a ton of great rust documentation, from the reference, the nomicon, the cargo book, the async book, rust by example, docs.rs, the standard library documentation, and for compiler contributers, there's rustc-dev-guide and nightly-rustc, and probably even more i'm forgetting.

the problem is, most of these only have clear and prominent links to one or two of these sites, making it very difficult to find all the documentation a new user will need.

additionally, rust could solely use a standard glossary, many terms are not described precisely enough as to prevent confusing.

7 Likes

here's my attempt to address this, The Rust Documentation Directory

Another problem with documentation discovery is too much evergreen documentation (things that are always relevant) is published in more ephemeral locations, like blogs. For instance, in another thread someone was talking about clap::builder::value_parser!s use of deref specialization. Documentation exists for this in a couple of blog posts. If you find the "wrong one", you get a a less refined iteration of the pattern.

We need a discoverable place to document these kinds of things. There is Introduction - Rust Design Patterns which could potentially house it. At times, that hasn't gotten much love though it seems it has gotten more recently and you have to know about it in the first place.

4 Likes

This looks very similar to the list on https://www.rust-lang.org/learn, which is the "Learn" link in the header. Do you have any insight on why that page wasn't discoverable to you?

1 Like

I explain all my issues with that page in this URLO comment, but the biggest one is the presentation of that page suggests that it would only be useful for those who are just starting to learn rust. It looks like a tutorial, not an index of documentation. As someone who has been using rust for a while, my immediate thought when looking at that page is "I don't belong here".

5 Likes