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.
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 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.
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. 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).
I just discovered that little button at the top of 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
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.
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.
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
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
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, ...
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, ....
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.
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.
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.
)
