Suggestion: Shorter, clearer chapters for beginners

[PlanBernhard]

Hello,

I really appreciate the Rust Book, but as a beginner, I found some chapters (like the one on Streams) quite lengthy and sometimes overwhelming. I think about 50–70% of the content could be removed or summarized without losing the key information. A more concise approach would help newcomers understand the core concepts faster and might prevent them from giving up too soon.

Thank you for your work and consideration!

[iampi31415]

@PlanBernhard i don't mind how it is written but there is a shorter version https://jasonwalton.ca/rust-book-abridged/

[StefanSalewski]

but as a beginner, I found some chapters (like the one on Streams) quite lengthy

As a beginner, you should like the verbosity -- a lot of people do. For a compact book, you might consider my https://rust-for-c-programmers.com/. For the https://jasonwalton.ca/rust-book-abridged/ which I discovered a bit late: The author put a lot of work into it, but might have retired now. I read a few pages, but now hesitate to really advertise it. For the official book, note that we have the original, and the one from Brown University. It is a matter of task which you prefer.

And please note, that Rust is a complex language. It is not possible to teach the foundations on 300 pages, as some of the Amazon titles promise.

[PlanBernhard]

@StefanSalewski My feedback was not about the technical aspects, but rather about the writing style. At the beginning of the book, it is stated that it is not intended for people with no programming experience, but then the book tends to overcomplicate things. Especially problematic is the lack of a clear thread; there are countless instances of “more about that later” and then later “as you saw in chapter X,” which is not good writing.

I understand the book is free, but this structure makes it difficult for newcomers, as they constantly have to jump between chapters to recall previous information. Normally, when writing a book, you tell the story from start to finish, and everything in between provides the information the reader needs at that moment, without postponing explanations to future chapters: "show, don't tell".

1. Positive Aspects
   Clarity: The explanations are generally clear and logically structured, which is great for technical writing.
   Tone: The tone is friendly and encouraging, making complex topics approachable.
   Use of Examples: Frequent use of code listings and practical examples helps illustrate abstract concepts effectively.

2. Areas for Improvement
   a. Sentence Structure & Flow
   Long Sentences:
   Many sentences are quite long and contain multiple clauses. This can make the text harder to follow, especially for readers new to the topic.

Example:
"Recall how we used the receiver for our async channel earlier in this chapter in the “Message Passing” section. The async recv method produces a sequence of items over time. This is an instance of a much more general pattern known as a stream."

Suggestion:
Break up long sentences and use more punctuation to guide the reader.

Passive Voice:
The text sometimes uses passive constructions ("This is an instance of..."), which can make explanations less direct.

Suggestion:
Favor active voice to make the writing more engaging.
Example:

"This is an instance of a much more general pattern known as a stream."
could become
"We call this general pattern a stream."

b. Repetition & Redundancy
Conceptual Repetition:
Some ideas are repeated in similar words within a short space ("iterators are synchronous, while the channel receiver is asynchronous. The second is the API. When working directly with Iterator, we call its synchronous next method...").

Suggestion:
Combine related points and avoid restating the same information unless it adds clarity.

c. Consistency & Terminology
Consistent Naming:
Occasionally, the text switches between talking about "the async channel receiver," "ReceiverStream," and "stream" without always clarifying the relationship.

Suggestion:
Introduce new terms clearly and stick to one term for each concept unless a distinction is necessary.

d. Transitions & Structure
Section Transitions:
Some paragraphs jump directly into code or new ideas without a clear transition.

Suggestion:
Use brief transition sentences to connect sections and guide the reader through the logic.

Headings & Summaries:
While the text uses code listings as natural breaks, more descriptive subheadings and occasional summaries would help orient the reader.

e. Reader Engagement
Questions & Prompts:
The text could occasionally address the reader directly or pose rhetorical questions to keep them engaged.

Suggestion:
For example: "You might wonder why we need to pin the stream here—let's explore that."

Bad Practices to Avoid in Technical Writing
Overloading Sentences:
Avoid packing too much information into a single sentence.

Assuming Knowledge:
Don't assume the reader knows all jargon; briefly define terms when first introduced.

Neglecting Flow:
Ensure each paragraph logically leads to the next.

Example Revision
Original:
"We saw a sequence of items back in Chapter 13, when we looked at the Iterator trait in The Iterator Trait and the next Method section, but there are two differences between iterators and the async channel receiver. The first difference is time: iterators are synchronous, while the channel receiver is asynchronous. The second is the API. When working directly with Iterator, we call its synchronous next method. With the trpl::Receiver stream in particular, we called an asynchronous recv method instead. Otherwise, these APIs feel very similar, and that similarity isn’t a coincidence. A stream is like an asynchronous form of iteration. Whereas the trpl::Receiver specifically waits to receive messages, though, the general-purpose stream API is much broader: it provides the next item the way Iterator does, but asynchronously."

Edited:
"Back in Chapter 13, we explored the Iterator trait and its next method. There are two important differences between iterators and the async channel receiver. First, iterators are synchronous, but the channel receiver works asynchronously. Second, their APIs differ: with Iterator, we use the synchronous next method, while with trpl::Receiver, we call the asynchronous recv method. Despite these differences, the APIs are intentionally similar. This is because a stream is essentially an asynchronous form of iteration. While trpl::Receiver waits for messages, the general-purpose stream API can provide any kind of item, just like Iterator—only asynchronously."

[PlanBernhard]

And please note, that Rust is a complex language. It is not possible to teach the foundations on 300 pages, as some of the Amazon titles promise.

I don't believe in shortcuts to success.

[StefanSalewski]

Thank you very much for this detailed list. I had a lot problems to interpret your initial post, but this clarification makes your concerns much clearer.

I don't know if the maintainers of the official books consider larger changes. Actually I doubt it. Note that many people like the official books a lot as they are -- the rating at Amazon is very high.

My book has a completely different style. For the case that you are still in the learning phase, I would strongly recommend having also a look into my book. I would like to have some more serious feedback at the GitHub issue tracker, in the form you provided here. I can also recommend the book of Jim Blandy "Programming Rust" -- I once read a borrowed one of the second edition. It had some issues, but explains a lot of details, and I got the feeling that the authors know really a lot of the Rust language. So when the third edition will become available, we might consider buying it.

[EDIT]

Your analysis in your second post is really quite good. I really wonder why your first post -- the headline and the text content, was so weak? I actually hesitated to reply. Well, perhaps you were just a bit frustrated and tired. But for the future, just unmotivated complaining is typically not helpful -- I typically ignore it, and it makes me unmotivated.

[PlanBernhard]

@StefanSalewski Sorry, at the time of my criticism, I didn’t think to explain my point of view more thoroughly. I was mainly focused on my own perspective and also under a bit of time pressure. I realize now that wasn’t helpful, and I’ll try to be more constructive in the future. On top of that, it actually took me a bit more time than I thought to put together my detailed criticism.

Thank you for your book suggestion—I will definitely check it out. I really appreciate your recommendation!
Same goes for you, @iampi31415

However, I’d also like to add that I don’t think everyone needs to write their own book. In my view, it would be much more effective if knowledge could be centrally gathered and shared, allowing everyone to contribute their expertise to a common pool.

[EDIT]
Just to clarify, my perspective is based on my background as a writer, particularly in German. I don’t think my way is superior—it’s simply the approach I’m most familiar with.

[StefanSalewski]

However, I’d also like to add that I don’t think everyone needs to write their own book.

Yes, I agree. I actually wonder myself why at Amazon there are now more than 100 Rust books. But I think that the two official Rust books will never change much. They recently got a new chapter about async, but I assume they will not change a lot. Many people like the books very much like they are. When I read the official book in October 2023, I discovered more than 100 small issues, and I posted about a dozen to the Github issue tracker, but most have been rejected that time. Now the new maintainer has fixed at least the most serious ones. I created my book, because I had the feeling it would be nice to have a compact book, for people with already some experience in systems programming, for which the official books are a bit too verbose and boring. I think my book is indeed the only one of this kind. The book of Jim Blandy is close, but has also very verbose parts, and I think parts of that book explain too many details. And I was not really happy with the order in which the content was presented -- the same for the official book. But of course it is difficult to find serious readers for new books. Placing them at Amazon might help, maybe promoting them with a few 5 star reviews.

[PlanBernhard]

However, I’d also like to add that I don’t think everyone needs to write their own book.

Yes, I agree. I actually wonder myself why at Amazon there are now more than 100 Rust books. But I think that the two official Rust books will never change much. They recently got a new chapter about async, but I assume they will not change a lot. Many people like the books very much like they are. When I read the official book in October 2023, I discovered more than 100 small issues, and I posted about a dozen to the Github issue tracker, but most have been rejected that time. Now the new maintainer has fixed at least the most serious ones. I created my book, because I had the feeling it would be nice to have a compact book, for people with already some experience in systems programming, for which the official books are a bit too verbose and boring. I think my book is indeed the only one of this kind. The book of Jim Blandy is close, but has also very verbose parts, and I think parts of that book explain too many details. And I was not really happy with the order in which the content was presented -- the same for the official book. But of course it is difficult to find serious readers for new books. Placing them at Amazon might help, maybe promoting them with a few 5 star reviews.

I see. Thank you for the background information. That makes complete sense. The book scene is generally a tough market—there’s far more supply than demand. Additionally, a recent study published in my country just a few weeks ago found that fewer and fewer people are reading. Unless you have a name like J.K. Rowling, Stephen King, J.R.R Tolkin, ... it seems almost impossible to attract a large readership. This is true even for new authors who are backed by major publishers. Unfortunately, many books remain on the fringes of public attention.