3 ms·

> [...] include actual reasoning about why things are how they are in Rust and that they seem pretty open about drawbacks of the choices. This trait of documen

> [...] include actual reasoning about why things are how they are in Rust and that they seem pretty open about drawbacks of the choices. This trait of documentation (the "why" & openly discussing pros and cons) seems to be a property of great systems being well-documented.

derefr 9y ago
I'm not sure—I think it's more, in this case, that Rust assumes the developers learning about it have specific goals: namely, to evaluate Rust vs. C/C++. So every resource that teaches Rust couches the discussion in terms of justifying why the particular design being presented is better (from the Rust maintainers' perspective) when compared to designs in existing languages, even if it makes other sacrifices to be such. 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.
- steveklabnik 9y ago
  > Rust assumes the developers learning about it have specific goals: namely, to evaluate Rust vs. C/C++. We don't assume that. From https://doc.rust-lang.org/book/second-edition/ 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++.
  - Agathos 9y ago
    I think derefr was inferring (or imagining?) a subconscious need to defend certain decisions, even if C and C++ are not prerequisites. As a post-structuralist, I generally approve of reading the author's stated intentions and responding, "Yes, well, that's one interpretation." :P
  - binarycrusader 9y ago
    For what it's worth, rust's often introspective approach to documentation and community is one of its defining virtues in my opinion. 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!
    - steveklabnik 9y ago
      <3
  - derefr 9y ago
    Sorry if I wasn't clear; I didn't mean to imply that the Rust maintainers assume any prerequisite knowledge of C/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.

derefr 9y ago

I'm not sure—I think it's more, in this case, that Rust assumes the developers learning about it have specific goals: namely, to evaluate Rust vs. C/C++. So every resource that teaches Rust couches the discussion in terms of justifying why the particular design being presented is better (from the Rust maintainers' perspective) when compared to designs in existing languages, even if it makes other sacrifices to be such. 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.

steveklabnik 9y ago
> Rust assumes the developers learning about it have specific goals: namely, to evaluate Rust vs. C/C++. We don't assume that. From https://doc.rust-lang.org/book/second-edition/ 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++.
- Agathos 9y ago
  I think derefr was inferring (or imagining?) a subconscious need to defend certain decisions, even if C and C++ are not prerequisites. As a post-structuralist, I generally approve of reading the author's stated intentions and responding, "Yes, well, that's one interpretation." :P
- binarycrusader 9y ago
  For what it's worth, rust's often introspective approach to documentation and community is one of its defining virtues in my opinion. 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!
  - steveklabnik 9y ago
    <3
- derefr 9y ago
  Sorry if I wasn't clear; I didn't mean to imply that the Rust maintainers assume any prerequisite knowledge of C/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.