rust book refers to 'str' primitive type as if it has already been introduced #30162
Comments
|
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. |
|
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:
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. |
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.
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:
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. |
|
To be clear here, I'm not saying the situation isn't unfortunate, It's why there's going to be a reorganization. |
|
#30271 is a quick fix to help a bit for a related problem, but it doesn't fix this exact issue. |
Some history: While getting Rust to 1.0, it was a struggle to keep the book in a working state. I had always wanted a certain kind of TOC, but couldn't quite get it there. At the 11th hour, I wrote up "Rust inside other langauges" and "Dining Philosophers" in an attempt to get the book in the direction I wanted to go. They were fine, but not my best work. I wanted to further expand this section, but it's just never going to end up happening. We're doing the second draft of the book now, and these sections are basically gone already. Here's the issues with these two sections, and removing them just fixes it all: // Philosophers There was always controversy over which ones were chosen, and why. This is kind of a perpetual bikeshed, but it comes up every once in a while. The implementation was originally supposed to show off channels, but never did, due to time constraints. Months later, I still haven't re-written it to use them. People get different results and assume that means they're wrong, rather than the non-determinism inherent in concurrency. Platform differences aggrivate this, as does the exact amount of sleeping and printing. // Rust Inside Other Languages This section is wonderful, and shows off a strength of Rust. However, it's not clear what qualifies a language to be in this section. And I'm not sure how tracking a ton of other languages is gonna work, into the future; we can't test _anything_ in this section, so it's prone to bitrot. By removing this section, and making the Guessing Game an initial tutorial, we will move this version of the book closer to the future version, and just eliminate all of these questions. In addition, this also solves the 'split-brained'-ness of having two paths, which has endlessly confused people in the past. I'm sad to see these sections go, but I think it's for the best. Fixes rust-lang#30471 Fixes rust-lang#30163 Fixes rust-lang#30162 Fixes rust-lang#25488 Fixes rust-lang#30345 Fixes rust-lang#29590 Fixes rust-lang#28713 Fixes rust-lang#28915 And probably others. This lengthy list alone is enough to show that these should have been removed. RIP.
…ankro Some history: While getting Rust to 1.0, it was a struggle to keep the book in a working state. I had always wanted a certain kind of TOC, but couldn't quite get it there. At the 11th hour, I wrote up "Rust inside other langauges" and "Dining Philosophers" in an attempt to get the book in the direction I wanted to go. They were fine, but not my best work. I wanted to further expand this section, but it's just never going to end up happening. We're doing the second draft of the book now, and these sections are basically gone already. Here's the issues with these two sections, and removing them just fixes it all: // Philosophers There was always controversy over which ones were chosen, and why. This is kind of a perpetual bikeshed, but it comes up every once in a while. The implementation was originally supposed to show off channels, but never did, due to time constraints. Months later, I still haven't re-written it to use them. People get different results and assume that means they're wrong, rather than the non-determinism inherent in concurrency. Platform differences aggrivate this, as does the exact amount of sleeping and printing. // Rust Inside Other Languages This section is wonderful, and shows off a strength of Rust. However, it's not clear what qualifies a language to be in this section. And I'm not sure how tracking a ton of other languages is gonna work, into the future; we can't test _anything_ in this section, so it's prone to bitrot. By removing this section, and making the Guessing Game an initial tutorial, we will move this version of the book closer to the future version, and just eliminate all of these questions. In addition, this also solves the 'split-brained'-ness of having two paths, which has endlessly confused people in the past. I'm sad to see these sections go, but I think it's for the best. Fixes rust-lang#30471 Fixes rust-lang#30163 Fixes rust-lang#30162 Fixes rust-lang#25488 Fixes rust-lang#30345 Fixes rust-lang#29590 Fixes rust-lang#28713 Fixes rust-lang#28915 And probably others. This lengthy list alone is enough to show that these should have been removed. RIP.
Some history: While getting Rust to 1.0, it was a struggle to keep the book in a working state. I had always wanted a certain kind of TOC, but couldn't quite get it there. At the 11th hour, I wrote up "Rust inside other langauges" and "Dining Philosophers" in an attempt to get the book in the direction I wanted to go. They were fine, but not my best work. I wanted to further expand this section, but it's just never going to end up happening. We're doing the second draft of the book now, and these sections are basically gone already. Here's the issues with these two sections, and removing them just fixes it all: // Philosophers There was always controversy over which ones were chosen, and why. This is kind of a perpetual bikeshed, but it comes up every once in a while. The implementation was originally supposed to show off channels, but never did, due to time constraints. Months later, I still haven't re-written it to use them. People get different results and assume that means they're wrong, rather than the non-determinism inherent in concurrency. Platform differences aggrivate this, as does the exact amount of sleeping and printing. // Rust Inside Other Languages This section is wonderful, and shows off a strength of Rust. However, it's not clear what qualifies a language to be in this section. And I'm not sure how tracking a ton of other languages is gonna work, into the future; we can't test _anything_ in this section, so it's prone to bitrot. By removing this section, and making the Guessing Game an initial tutorial, we will move this version of the book closer to the future version, and just eliminate all of these questions. In addition, this also solves the 'split-brained'-ness of having two paths, which has endlessly confused people in the past. I'm sad to see these sections go, but I think it's for the best. Fixes rust-lang#30471 Fixes rust-lang#30163 Fixes rust-lang#30162 Fixes rust-lang#25488 Fixes rust-lang#30345 Fixes rust-lang#28713 Fixes rust-lang#28915 And probably others. This lengthy list alone is enough to show that these should have been removed. RIP.
Some history: While getting Rust to 1.0, it was a struggle to keep the book in a working state. I had always wanted a certain kind of TOC, but couldn't quite get it there. At the 11th hour, I wrote up "Rust inside other langauges" and "Dining Philosophers" in an attempt to get the book in the direction I wanted to go. They were fine, but not my best work. I wanted to further expand this section, but it's just never going to end up happening. We're doing the second draft of the book now, and these sections are basically gone already. Here's the issues with these two sections, and removing them just fixes it all: // Philosophers There was always controversy over which ones were chosen, and why. This is kind of a perpetual bikeshed, but it comes up every once in a while. The implementation was originally supposed to show off channels, but never did, due to time constraints. Months later, I still haven't re-written it to use them. People get different results and assume that means they're wrong, rather than the non-determinism inherent in concurrency. Platform differences aggrivate this, as does the exact amount of sleeping and printing. // Rust Inside Other Languages This section is wonderful, and shows off a strength of Rust. However, it's not clear what qualifies a language to be in this section. And I'm not sure how tracking a ton of other languages is gonna work, into the future; we can't test _anything_ in this section, so it's prone to bitrot. By removing this section, and making the Guessing Game an initial tutorial, we will move this version of the book closer to the future version, and just eliminate all of these questions. In addition, this also solves the 'split-brained'-ness of having two paths, which has endlessly confused people in the past. I'm sad to see these sections go, but I think it's for the best. Fixes #30471 Fixes #30163 Fixes #30162 Fixes #25488 Fixes #30345 Fixes #29590 Fixes #28713 Fixes #28915 And probably others. This lengthy list alone is enough to show that these should have been removed. RIP.
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
strtype, 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 findstrthe obvious choice, but the reader hasn't heard ofstrat 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
strwould be less confusing at this point.The text was updated successfully, but these errors were encountered: