Thoughts (critique) about the Rust book

#1

Hi, Over the last several days I have read through the Rust book several times and have written down some of my thoughts. I would now like to share them with you, because I would like to see the Rust book improve over time and become even more awesome than it already is :wink:

Before I give you the link to the Gist, I would like to say some things:

  • What I am going to share with you are my thoughts, opinions and ideas for improvement. I don’t want to impose them on anyone.

  • In no way am I trying to belittle the writers and say that my ideas are better, I am merely sharing what I think could be an improvement over the current state of the book.

  • I sometimes use you should or it should. Don’t take this the wrong way, please :smile: I didn’t always try to find the most diplomatic way of putting my thoughts on paper. So ignore such comments and just remember the message I tried to convey.

  • I didn’t give comments about chapters in the Advanced section, but I think there is enough to discuss already with the rest. You will see what I talk about when you read the document.

Now that’s out of the way, here is the gist: https://gist.github.com/azerupi/e89ce98d4a6f32c30f49

If I can be of any further help, I would be glad to do so. Also it wouldn’t bother me to help write / rewrite some parts of the docs if needed. (when I have time of course :blush: )

I curious to see what you think about it,

Mathieu

#2

I think your proposed structure here is somewhat similar to the restructure the rustbyexample.com recently did so I think comparison is warranted. However, I would not propose you use it as a model either because the two sites use different teaching styles and keeping things different is a good thing.

#3

Thank you for taking the time to read through my text :slight_smile:

I didn’t use rustbyexample.com as a template, but the fact that the structure shares a lot of similarities with what I propose does indicate that it’s not such a bad one :wink:

Actually, when I was writing this document I remembered several “Tutorials” (they are more like online books) from Openclassrooms. It’s originally a french website that has a huge amount of programming tutorials. I learned C, C++, HTML and JavaScript from their website and I really enjoyed reading those. They were not hard to follow, took the time to explain everything building up from nothing. If you understand some french here is their C++ tutorial

Everybody might not like that kind of style, especially more professional programmers. But I remember that I really enjoyed it as a beginner and I always wanted to learn more. If we could achieve that with the Rust book it would be an enormous win for Rust (in my opinion).

#4

I just discovered that little button at the top of rustbyexample.com to change the font :open_mouth:

That should definitely be implemented in the docs, I can’t stand that serif font anymore ! :wink: They have implemented some nice things: sidebar can be hidden, little green check marks when read, search, … And their overall styling looks nicer too. No offence to the designer of the doc :blush:

#5

Yeah, it’s nice. I like the dark themes myself. rustbyexample uses gitbook whereas the book uses rustbook which is essentially written to be similar to gitbook but in rust. rustbook is currently pretty primitive and hopefully will be expanded in the future.

I don’t have a strong opinion about your suggested structure though. It seems reasonable but I think there are multiple reasonable ways it could be structured. In general though, I’m a fan of grouping similar tools together into categories as you suggest.

#6

thank you for writing this. I appreciate it.

The current organization is a result of two things: history, and feedback. Some people want to see the more reference-y ‘syntax and sematnics’ moved up, but I bumped it back because when it was at the forefront, many people wanted to just dive in.

One TOC can’t satisfy everyone.

I will say that the TOC may change in the near future but I cannot say way, just stay tuned :wink:

I apprecaite and take seriously all of this feedback.

#7

@steveklabnik Haha so secretive :wink:

I’m glad you liked my feedback ! Honestly, at first I was a bit afraid, I wasn’t sure how it would be received. But I’m glad to see that I was completely wrong and that the Rust community is truly an open-source community that takes every bit of feedback into account. I really like that :blush:

I think that’s because at the moment, almost all the users are already highly familiar with one or several other programming languages. But as time goes by and Rust gains in popularity, people that are completely new to programming might be interested to learn Rust.

At the moment I wouldn’t recommend Rust as someone’s first programming language, because even I who has learned C and C++ as first languages, had a hard time grasping the basics of Rust. Once you do understand the basic concepts, it’s a piece of cake, but it takes a couple of hours of reading and frustration before you get there :smile:

#8

Note that the intro does mention the different ways of reading the book.

I wish that could be somehow more prominent though. I don’t know how to accomplish that.

#9

I know, but somehow I still expected it to be chronological. :confounded:

One more suggestion:
I think the book could use some boxes / divs with different styling to indicate non-vital additional info. Important notes (gotchas), warnings, …

Like contextual backgrounds in Bootstrap or the ones they use on Openclassrooms

This gives the ability to highlight the more important stuff

Actually I think I have seen something that looks like that in the doc. But it’s not used extensively and sometimes it’s used for quotes, sometimes for raw text, …

#10

I’ll reiterate my suggestion I made on users.rust-lang.org regarding the Unsafe chapter: Add the following section (hereby donated to the rust project):

Why would I use unsafe?

There are two situations that call for unsafe code:

  • You need to override the safety rules (and are willing to guarantee that your code is sane even in the face of the relaxed safety rules). In those cases, you really cannot do what you need to because a safety check got in the way. In this case use unsafe and program as if the next person who uses the code is a violent psychopath who knows where you live.
  • You cannot achieve the required performance within safe code. There are times when you want to eke out that last bit of performance, but cannot within the cozy confines of safe Rust. In those cases, you should first write the slow & safe version, and measure its performance. The profile will guide you to the parts of code that need unsafe features. Also you can use the slow version as a baseline against which to test.

In both cases, there may be libraries that supply safe interfaces over unsafe features that you may be able to use without writing unsafe code yourself. So when you find yourself in one of the above situations, it may be useful to look around if someone else has already come up with a solution you can reuse.

#11

I wouldn’t either. I would expect this to be at least two years out in the future. The main reason is this: what new programmers need is help and resources, and Rust has precious few at the moment. That’s far more important than the specific language they learn.

#12

Agreed, even though I think it could go quite fast because the community is very kind and helpful :blush: