I was just trying to say that he has an inherent bias towards non-systems programmers, therefore he will write in a way that is appealing to non-system programmers, which I believe is not the main audience of Rust. It is fine that he has this bias, its what he has been working on for the past few years, that’s fine.
Im sorry that my tone is harsh, I will work on that, thanks for the well thought criticism.
explaining the stack vs heap is pretty critical, though again, with my revision I have plans to address this.
I also had the feeling that I had to skim over a lot of "too basic systems programming" when I was going through the book... I decided to learn Rust and was excited to know what it brings to the table (borrow checker/ownership/traits...). This excitement faded away as I had to skim over pages and pages of documentation that were not meant for me at all. It got interesting eventually, but I had to push through, which I guess is far from optimal.
I agree, but it's going to be very many people's first systems programming language ... I agree, but it's going to be very many people's first systems programming language. Many Rubyists, for example, while programming for years, have never heard the words 'stack vs heap.'
@steveklabnik What is the focus of the docs? This needs to be crystal clear:
I think that if a Javascript programmer needs a system language, they already know some C/C++/D,... If they don't, they don't need Rust (this is a good thing!). So in my opinion the main docs should focus on those who need Rust, that is, people that need to solve systems programming problems, and probably have already some systems programming experience.
Having said that, I think it would be awesome to have "An introduction to programming with Rust" as an introduction to both programming and systems programming. But that is a completely different undertaking.
The current status quo is just one-size doesn't fit all, and it is good to discuss it.
@terpstra There are already several resources for C++ programmers interested in Rust: 1, 2, 3, 4, 5, 6 (older), 7, that’s compared to ie someone coming from Haskell, which only this that I could find.
Anyway, I would echo what @Toby_S and @skade already said. My own view on this is that if you’re already familiar with C++ then read only the parts that you’re not familiar with and skim over the others. Why do you think that the book should be tailored towards one’s individual needs? Rust is already being used by a wide variety of programmes including those who have previous experience with system, web, functional programming or even just shell scripting.
Maybe this expectation comes from the fact that Rust markets itself as “a systems programming language” and I understand where one can come to have such an expectation from people learning Rust as you have, but I would like to think that in order to learn a systems programming language, one doesn’t need to know yet another systems programming language.
Think 20 years ago, how would you feel if you wished to learn C++ and the requirement for it was that you first had to master assembly? There’s no need to learn Perl before starting with Ruby, or Java before JavaScript ,nor C and Pascal before Go etc. Don’t you think that this served to the benefit rather than to the detriment of those languages?
I think that Rust is a language strong enough to stand on its own merit, without being bogged down by the legacy of its predecessors.
Besides, Rust builds on much more than just C++, it takes ideas from Cyclone, OCaml, Haskell, Scala, Ruby, Python, Erlang and many others - shouldn’t members of all those communities feel that the documentation should be tailored more towards them? I think that it is easy to see how it is an impossible task to please everyone 100% of the time, so the book tries to be as inclusive as possible.
I would much rather have information in the book, which can be skipped, rather than not have the info there at all - someone may need it.
Also @steveklabnik has been with Rust for a long time and has always been very willing to make any sensible changes to the documentation, attacking his background as a Rubyist as @sinistersnare has done is apart from being rude and unfair, as Steve has written the very first book that got many people even interested in Rust and has involved in the language since its very early stages as a public project, as such I can assure you that he knows what he is talking about.
I am glad for everybody who’s trying to improve Rust one way or another as we all just want the best product possible, just please take into account that there is a wide variety of people interested in Rust and taking the view that the documentation should be tailored towards your individual background is somewhat exclusive.
Yeah, I went to bed feeling pretty shitty about myself from this post, (the ‘reply to’, not the OP) to be honest about it. Even though I’ve written C since I was a child, and C++ in the pre-modern era. While it’s true that systems hasn’t been my professional area of focus, I see that as a good thing for Rust, not bad. If Rust is just for C++ people, it will fail to catch on. Pointed criticism, as in the OP, is good, but borderline personal attacks is not.
But separate from that, I’ve been planning some TOC changes to the book that should help alleviate this sort of issue, I’ve been thinking about it for weeks. I wanted to wait till beta dropped first. So, expect some changes, and I think you’ll like them.
I can only second this. The book should not presuppose a couple of years experience in C++, but instead try to be informative and helpful for programmers with a non-systems programming background, too. As said above (by @steveklabnik IIRC), Rust might as well be the first low-level programming language for a lot of people in the future. They should feel welcomed and well informed by the book just as well.
By the way, his critique doesn’t actually require that much change. There just needs to be more guided direction. He basically seems to want these things:
This isn’t to say TOC changes shouldn’t be made but a targeted guided intro might go a long way towards smoothing out these issues.
First of all, I agree with the @terpstra’s OP and I was preparing a similar (but less detailed) list myself, that I will post later.
I learned the basics of rust already from afar by lurking on the rust-dev list, but it’s been about a year since I touched it. Now, when I saw that the book was laid out as “basics”, “intermediate”, “advanced”. I saw that “basics” really did seem to consists of basics (for loops, strings, variable bindings…) so I skipped it entirely. It was odd that Cargo came first in Intermediate, but since the front page said I could read the sections “in any order” I just skipped it… avoiding terpstra’s boredom experience.
The fact that there are different audiences for the book means you need some way to teach the necessary concepts to those who don’t know them—without boring those that already do know them. And as @terpstra said, ownership is so central to rust that introducing it in Intermediate may be too late.
So I would propose the following:
*. Every language I’ve seen that requires this (*p, *q) uses the term “pointer” (C/C++/D), while every language that doesn’t (p, q) uses “reference” (C++, D, Java, C#, this list is very long).)[quote="steveklabnik, post:24, topic:1816, full:true"] Yeah, I went to bed feeling pretty shitty about myself from this post, (the 'reply to', not the OP) to be honest about it.[/quote] That's awful! I started this thread with intent to help you improve the already quite good documentation. I certainly appreciated your work when I wanted to start reading about Rust. So, thank you!
Yes. My main complaints were essentially about the organization of sections and discussion of ownership. steve already indicated he has plans to reorder the TOC, so that sounds great!
My thoughts with regard to sections:
Deprioritize Cargo and focus on Rust first; maybe move Cargo all the way to advanced topics.
Move Traits before Closures and Associated Types (still in intermediate)
Split the pointers+lifetime up into sections "move and copy", "RAII and drop", "Borrowing", "Boxes", and "Lifetimes"
On the topic of borrowing and lifetimes, a lot of people here have been talking about "systems programming". I think this is a red herring. You can perfectly well explain a lot of the core concepts WITHOUT reference to the heap or stack. Just explain it from the point of view of when resources are released or copied. People who know how this works will read between the lines. People who don't, don't need to be distracted!
For "Move+Copy", just explain in terms of copying and ownership. By default, Rust transfers ownership, and can't use the old name. If you indicate support for Copy (via derive so no need to have covered traits yet), then you get a copy instead of move. Every programmer understands copying. You can hint that this ties into orderly release of resources, leading into the next section...
For "RAII and drop", first explain some objects need to have something done when they are deleted. For example, a thread should be joined (or whatever). Show that this happens when the object goes out of scope to demonstrate the power of RAII. Mention that this is a big advantage compared to garbage collected languages. Hammer home that Drop conflicts with Copy, so you need either move semantics or borrowing (segue into next section).
For "Borrowing", the existing explanation already makes no mention of the stack/heap.This part of the text was fine, btw.
Only once you get to "Boxes", which I'd put into intermediate Rust, does the heap actually appear. Yet, you can avoid getting into the details here too! Show a recursive data structure like a struct List { dat:i32, next: Option<List> }. Demonstrate that without "Box" you have an infinitely large struct. Explain that Box means out-of-place storage. Maybe include a classic example like reversing a linked list. Tie this back together with resource management; Box's drop cleans up the out-of-place storage. Mention that the "out-of-place" storage is the heap, with a link to the Appendix for explanation, but don't get hung up on it. You can also readily explain RC in these terms; it's only when all the clones of RC get dropped that the out-of-place object gets released.
For "Lifetimes", I don't understand them well enough myself yet to comment on the best presentation approach.
I was thinking about the proposal to move the cargo section to advanced topics. One topic that is not yet (?) part of the book is how the compiler can be used. Like various hints at command line options and such. Maybe a tooling section or so with cargo and rustc and its uses and options could come in handy. Yeah, I know there’s always man, but still 
This has many similarities to what I’m planning.
To re-state, it was not you, and @sinistersnare has already apologized over at Reddit, so let's just all call it a mistake and move on.
Deprioritize Cargo and focus on Rust first; maybe move Cargo all the way to advanced topics.
Cargo is the main interface by which people should be using Rust on a day-to-day basis.
Split the pointers+lifetime up into sections "move and copy", "RAII and drop", "Borrowing", "Boxes", and "Lifetimes"
This is one of the kinds of things I'm doing, for sure.
I think cargo should be in the forefront. An annoyance of C++ projects is they may often have complicated build instructions which makes contributing possibly annoying depending on your experience with the specific project.
For example: someone finds something minor (typo maybe) but has never setup a build environment before…well, you gotta download that specific version of Visual Studio but it’s deprecated and the developers haven’t gotten around to updating. Is it still downloadable? Maybe it requires Pro and maybe not. He gonna buy VS for this minor fix? What about Qt Creator? Maybe it works but you gotta do these workaround steps. 64-bit? Does that require extra steps? What about CodeBlocks or Eclipse? Any easier?
If in 5 years, 75% of Rust projects can be contributed to regardless of platform strictly by:
git clone repository_location
cd folder
cargo build && cargo test
then putting cargo new on the first page seems like a worthwhile sacrifice. I know things do get more complicated but it seems like a really good precedent to set.
My only problem with this approach is that it seems to address the question of people without C++ experience the way of making certain things invisible to them, which I don't think is fair, they too deserve the full picture. What's the problem with simply skipping the stack vs heap explanation - why does it need to be (re)moved?
Good idea, but as far as I am aware, we don't refer to some concepts this way. For example, I would think that RAII goes under the framework of "lifetimes" and "ownership", I don't normally see the term RAII much in Rust-related discussions.
I had the same experience, a while back, where I wanted to learn about Rust and got bogged down (I know, it isn't hard) with Cargo as step one.
Maybe something that would help, unless it is antisocial with whoever is hosting it, is to start with playpen links. Writing hello world and talking about loops and matching and stuff seems like the perfect scale for playpen, and you can even have links to demo the relevant code, and get folks running it right away.
This would have the advantage that you could skip/defer "installing Rust", "Hello Cargo", "Crates and Modules", "Testing and Documentation", and such stuff that lives before "pointers" and "ownership", which I think is where many of the cool differences live.
In any case, it seems super useful to have a few worked examples, not unlike the fragments in the Book, that one can press "build" and see what happens, and then perhaps comment/uncomment some code and press "build" again to see something different. The rust-lang.org front page is a great example of how I (personally) would have liked to learn these things; fun and accessible!
Maybe rustbyexample.com already does this, though. I like it a bunch too (but it feels it could use some love).
I think this is a great idea. Embedding runnable snippets of code in the guide would be awesome, and that would probably allow for punting on cargo for just a bit.
It actually was that way a while back, I think that the main reason it was discarded is because you can't always make something that actually compiles while explaining some concept.
That's one issue, but another is that rustbook does not pass the correct flags to rustdoc to enable the links. That's a bigger one.
I don’t think they were ever embedded in the sense that they are in rustbyexample. They were links to the playpen like the std library documentation.
Even rustbyexample only allows a single playpen instance on a page (though that restriction might be removable now). This could be a problem for the book where there are many examples per page.
I think there used to be (can’t find it currently) some way to specify setup code which only is displayed when the example actually is actually run. I think that would help what you were suggesting.
Aha, makes sense. Is this considered to be a bug or something like a nice to have feature?
That's correct, I somehow forgot about that.
I agree with @tikue that it would be nice to have it embedded this way in the future, although I'd imagine most people have an editor open beside the book anyways, typing out the code shown.
Is this because converts from C++ are too few?