# Thoughts (critique) about the Rust book **URL:** \ **Category:** documentation\ **Created:** [June 3, 2015, 3:47pm UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190 "2015-06-03T15:47:28Z")\ **Posts on this page:** 13\ **Page:** 1
**Author:** ![Azerupi](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/azerupi/32/1068_2.png) [@Azerupi](https://internals.rust-lang.org/u/Azerupi)\ **Post date:** [June 3, 2015, 3:47pm UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/1 "2015-06-03T15:47:28Z")
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 😉 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 😄 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](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 😊 ) I curious to see what you think about it, Mathieu ---
**Author:** ![mdinger](https://avatars.discourse-cdn.com/v4/letter/m/97f17d/32.png) [@mdinger](https://internals.rust-lang.org/u/mdinger)\ **Post date:** [June 3, 2015, 7:07pm UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/2 "2015-06-03T19:07:56Z")
I think your proposed structure here is somewhat similar to the restructure the [rustbyexample.com](http://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. ---
**Author:** ![Azerupi](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/azerupi/32/1068_2.png) [@Azerupi](https://internals.rust-lang.org/u/Azerupi)\ **Post date:** [June 3, 2015, 7:30pm UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/3 "2015-06-03T19:30:31Z")
Thank you for taking the time to read through my text 🙂 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 😉 Actually, when I was writing this document I remembered several “Tutorials” (they are more like online books) from [Openclassrooms](http://openclassrooms.com/). 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](http://openclassrooms.com/courses/programmez-avec-le-langage-c) 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). ---
**Author:** ![Azerupi](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/azerupi/32/1068_2.png) [@Azerupi](https://internals.rust-lang.org/u/Azerupi)\ **Post date:** [June 3, 2015, 7:45pm UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/4 "2015-06-03T19:45:52Z")
I just discovered that little button at the top of [rustbyexample.com](http://rustbyexample.com/) to change the font 😮 That should definitely be implemented in the docs, I can’t stand that serif font anymore ! 😉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 😊 ---
**Author:** ![mdinger](https://avatars.discourse-cdn.com/v4/letter/m/97f17d/32.png) [@mdinger](https://internals.rust-lang.org/u/mdinger)\ **Post date:** [June 3, 2015, 10:17pm UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/5 "2015-06-03T22:17:54Z")
Yeah, it’s nice. I like the dark themes myself. rustbyexample uses [gitbook](https://github.com/GitbookIO/gitbook) whereas the book uses [rustbook](https://github.com/rust-lang/rust/tree/master/src/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. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [June 4, 2015, 1:58am UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/6 "2015-06-04T01:58:02Z")
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 😉 I apprecaite and take seriously all of this feedback. ---
**Author:** ![Azerupi](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/azerupi/32/1068_2.png) [@Azerupi](https://internals.rust-lang.org/u/Azerupi)\ **Post date:** [June 4, 2015, 6:29am UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/7 "2015-06-04T06:29:32Z")
@steveklabnik Haha so secretive 😉 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 😊 > [@steveklabnik](#): > > 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. 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 😄 ---
**Author:** ![Manishearth](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/manishearth/32/50_2.png) [@Manishearth](https://internals.rust-lang.org/u/Manishearth)\ **Post date:** [June 4, 2015, 6:57am UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/8 "2015-06-04T06:57:09Z")
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. ---
**Author:** ![Azerupi](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/azerupi/32/1068_2.png) [@Azerupi](https://internals.rust-lang.org/u/Azerupi)\ **Post date:** [June 4, 2015, 7:21am UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/9 "2015-06-04T07:21:51Z")
> [@Manishearth](#): > > Note that the intro does mention the different ways of reading the book. I know, but somehow I still expected it to be chronological. 😖 **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](http://getbootstrap.com/css/#helper-classes-backgrounds) or [the ones they use on Openclassrooms](http://openclassrooms.com/courses/programmez-avec-le-langage-c/qu-est-ce-que-le-c-2#/id/r-1904210) 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, .... ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [June 4, 2015, 8:16am UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/10 "2015-06-04T08:16:57Z")
I’ll reiterate my suggestion I made on [users.rust-lang.org](http://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. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [June 4, 2015, 12:26pm UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/11 "2015-06-04T12:26:28Z")
> [@Azerupi](#): > > At the moment I wouldn't recommend Rust as someone's first programming language 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. ---
**Author:** ![Azerupi](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/azerupi/32/1068_2.png) [@Azerupi](https://internals.rust-lang.org/u/Azerupi)\ **Post date:** [June 4, 2015, 12:29pm UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/12 "2015-06-04T12:29:21Z")
Agreed, even though I think it could go quite fast because the community is very kind and helpful 😊 ---
**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\ **Post date:** [March 25, 2019, 8:24am UTC](https://internals.rust-lang.org/t/thoughts-critique-about-the-rust-book/2190/13 "2019-03-25T08:24:39Z")
Closed on March 25, 2019, 8:24am UTC This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.