rust book refers to 'str' primitive type as if it has already been introduced

[ntuckerxx]

I'm going through the rust book and have gotten to the Dining Philosophers section, at which point I've encountered the following text:

We choose the String type for the name, rather than &str.

None of the previous introduction has even mentioned a str type, so I had to go looking to find out what it is and how it differs from String. The example seems to assume that the reader would find str the obvious choice, but the reader hasn't heard of str at this point.

I'm brand new to rust myself so I'm not sure how this could be introduced better, but I think simply using String and not mentioning str would be less confusing at this point.

[steveklabnik]

Taking that path first, rather than going through Syntax and Semantics, is a "throw you in the deep end" style thing, so it's a bit faster and looser with the forward references. That said, this could be better, for sure.

[ntuckerxx]

I have to admit, it's a bit baffling that the "intro" path (Syntax and Semantics) is the one that requires you to jump out of TOC order of the book. When you get to the decision point, your only clue is:

Welcome! This section has a few tutorials that teach you Rust through building projects. You’ll get a high-level overview, but we’ll skim over the details.

If you’d prefer a more ‘from the ground up’-style experience, check out Syntax and Semantics.

The fact that the path labeled "tutorials" is apparently the "throw you in the deep end" path is very unclear. I would generally expect that the linear in-order path through the book's TOC is the friendliest and most self-contained intro to the language.

Furthermore, it's very strange that chapter 4 relies on a lot of knowledge that isn't introduced until chapter 5. I think the book could benefit from chapter 3 including a heavily abridged version of chapter 5 which introduces some of the important syntax early on without needing to crawl through every detail.

[steveklabnik]

I have to admit, it's a bit baffling that the "intro" path (Syntax and Semantics) is the one that requires you to jump out of TOC order of the book

I had it the other way, people complained, I moved it this way, people complain. Can't win :(

That said, the TOC is gonna change radically so that issue will apparently just Go Away.

The fact that the path labeled "tutorials" is apparently the "throw you in the deep end" path is very unclear.

It is literally above the fold on the first page of the book. Not sure how else to make the relationship even more clear.

[ntuckerxx]

It is literally above the fold on the first page of the book. Not sure how else to make the relationship even more clear.

I'm not seeing that clarity. The description of the two choices on the first page still leaves me with the impression that "Learn Rust" is going to be the easy path, and "Syntax and Semantics" is going to be thorough technical descriptions of every language feature (this is reinforced by a glance at the subheadings in chapter 5). Many programming intro books give you a choice between the soft, example-laden ease-in and the dry technical slog through more reference-like material, and I think perhaps the root issue (and the reason people complain either way you order it) is that it sounds like this is the choice you're offering, but it's not.

To be perfectly clear, here is the relevant text:

‘Learn Rust’ if you want to dive in with a project, or ‘Syntax and Semantics’ if you prefer to start small, and learn a single concept thoroughly before moving onto the next.

I read this as "follow 'Learn Rust' if you want your hand held through some sample code" and "follow 'Syntax and Semantics' if you prefer to learn a language by sitting down and reading the reference book."

Please keep in mind that at this point, I'm intentionally trying to look at this from a no-prior-knowledge point of view to help you understand what's frustrating people. Despite these small bumps, I find the book to be an excellent intro; I just think this navigational issue could be improved to get more people to successfully use the book.

[steveklabnik]

To be clear here, I'm not saying the situation isn't unfortunate, It's why there's going to be a reorganization.

[steveklabnik]

https://github.com/rust-lang/rust/pull/30271 is a quick fix to help a bit for a related problem, but it doesn't fix this exact issue.