This week marks a big change for the book.

Historically, I always had a vision for the docs, but with 1.0 coming, it was a struggle to just get everything documented and keep it from breaking, let alone put things together in the way that I wanted.

One way in which this manifested is in the split: https://doc.rust-lang.org/book/

After reading this introduction, you’ll want to dive into either ‘Learn Rust’ or

‘Syntax and Semantics’, depending on your preference: ‘Learn Rust’ if you want

to dive in with a project, or ‘Syntax and Semantics’ if you prefer to start

small, and learn a single concept thoroughly before moving onto the next.

Copious cross-linking connects these parts together.

Two paths through one book isn’t good. And “Learn Rust” never really came together in the way that I wanted it to. It only even came into existence the week before 1.0! I just didn’t have time to make things right. And then, it was time to work on API docs…

So, after doing a lot of chatting with a lot of people, including at the work week last week, I’ve come up with a reorganization of the book that makes me happy. It’s going to be great. I’m really excited about it. But it also means that there’s gonna be a lot of change, and things might not be coherent in the meantime. I don’t want to land a PR to change 300 pages of docs!

As such, I’ve made https://github.com/rust-lang/book. I’m going to be working on the book in that repo. Right now, it’s empty. But that won’t last long. This will let me work on things without screwing up the existing book for people, in the meantime.

You’ll notice one more thing: I’m using mdBook. This may be for good, or it may just be for development, but I’d like to think that it’s for good. We would have to sort out how to make it work with the build process. Or, the book might end up living in this repository permanently. There are still some unanswered questions. But in the worst case, things will just stay the same: once we’re happy with the new state of the book, we can import it back into tree, and things should Just Work. But maybe we can make them better, too.

Oh, and this also means I’m going to be a bit more liberal with pull requests to the book itself, as it’s a bit less important that the markdown be perfect, that it absolutely not introduce new forward references, or anything else.

Finally, it’d be nice to eventually move translations into the official docs as well. I’ve made

Rust Internals Better support translations for The Book? Over in , I talked about making changes to the book. One unfortunate part of this work is that it will also require a lot of work from the community translations http://doc.rust-lang.org/#community-translations This is one reason that I wasn’t... Reading time: 5 mins 🕑 Likes: 5 ❤

to chat about it.