This trait of documentation (the "why" & openly discussing pros and cons) seems to be a property of great systems being well-documented.
I would contrast this to e.g. the Erlang documentation. Erlang/OTP is a great system, and it's well-documented... but the documentation doesn't actually go into the "why" of various choices (e.g. why the BEAM has a module table with exactly two slots per key; why binaries are shared at ≥64 bytes; why clusters are fully connected; etc.)
But I think this makes sense, given the differing approach: unlike Rust, the Erlang/OTP platform is trying to facilitate an abstraction where you just write high-level declarative-ish code, and then improvements to the platform will make that code perform better over time.
Rust documents its decisions because it expects you to be someone who wants to know those things in order to make precisely those decisions (except you're choosing a systems language, rather than designing one.) Erlang leaves most of its internal implementation as a black box, because it expects you to treat it as a black box and derive advantages (in e.g. maintainability) from doing so.
We don't assume that. From https://doc.rust-lang.org/book/second-edition/
> This book is written for a reader who already knows how to program in at least one programming language. After reading this book, you should be comfortable writing Rust programs. We’ll be learning Rust through small, focused examples that build on each other to demonstrate how to use various features of Rust as well as how they work behind the scenes.
That is, we assume programming knowledge, but not specific programming knowledge. Many people come to Rust not knowing C or C++.
I rather meant that the goal of someone learning Rust "in anger" is for that person to quickly decide if Rust is the best language to use to solve the problem they have. And, if Rust is even a candidate in their solution-space, then usually C and C++ (and sometimes also Go or D or C#) are the other candidates the learner is considering learning. They're Rust's "neighbours" in its solution-space.
And so, Rust's documentation is well-written, but it's well-written specifically for this type of person learning Rust "in anger", with the goal of evaluating the language against its neighbours at the same time they're learning it. Such a person wants to see Rust's design-decision guts spilled out on the floor before them, so they can move on if those decisions are not to their liking.
This doesn't mean the documentation isn't approachable to people who don't have any such points of comparison! But just like a movie can be enjoyable for both kids and adults on different levels, Rust's documentation has both a "teaching you Rust" level and another "justifying Rust's departures from the Average Low-Level Language" level.
Growing up, I was constantly taught new things, without often being taught why. They "why" of things is just as important to me as the "how".
So thanks for all you've done and continue to do!
As a post-structuralist, I generally approve of reading the author's stated intentions and responding, "Yes, well, that's one interpretation." :P