Jun 16 2014

Historically, Rust has had a tough time with documentation. Such a young programming language changes a lot, which means that documentation can quickly be out of date. However, Rust is nearing a 1.0 release, and so that’s about to change. I’ve just signed a contract with Mozilla, and starting Monday, June 23rd, I will be devoting forty hours per week of my time to ensuring that Rust has wonderful documentation.

A year and a half ago, I was in my hometown for Christmas. I happened upon a link: Rust 0.5 released. I’ve always enjoyed learning new programming languages, and I had vaguely heard of Rust before, but didn’t really remember what it was all about. So I dug in. I loved systems programming in college, but had done web-based stuff my entire professional life, and hadn’t seriously thought about pointers as part of my day-to-day in quite some time.

There was just one problem: Rust was really difficult to learn. I liked what I saw, but there was very little of it. At the same time, I had been working on some ideas for a new toolchain for my book on hypermedia APIs, but wanted to try it out on something else before I took the time to port the content. And so, Rust for Rubyists was born. I decided that the best way to teach people Rust was to mimic how I learned Rust. And so, as I learned, I wrote. It ended up at about fifty pages of two weeks of work. I never contributed it to the main repository, because for me, it was really about learning, both about my ebook toolchain as well as Rust itself. I didn’t want the burden that came with writing an official tutorial, making sure that you cover every single feature, pleasing every single Github contributor…

After learning Rust, I decided that I really liked it. No other language provided such a promising successor to C++. And I really missed low-level programming. So I kept evangelizing Rust, and every so often, contributing official documentation. I figured that even if my low-level chops weren’t up to the task of writing actual patches, I could at least help with my writing skills. I’d previously contributed lots of documentation to Ruby and Rails, so it was something that was very familiar to me. I’ve often found that I start with documentation and then move into contributing code, once I get my head wrapped around everything. Writing is part of my own process of understanding.

Rust for Rubyists was a great hit, even amongst non-Rubyists (damn my love of alliteration!). Six months ago, on the eve of the first anniversary of the initial release of Rust for Rubyists, I gave a talk at the Bay Area Rust meetup, specifically on the state of Rust’s documentation. In it, I laid out a plan for how I envisioned docs looking in the future. In the last six months, a lot has improved, but a lot hasn’t. But no more! I’m now going to be able to allocate a significant amount of my time on getting documentation done.

I’m also pleased in a meta-sense. You see, by contracting someone to work on documentation full-time, Mozilla is indicating that they take Rust and its future very seriously. You can (and I do) talk a lot of trash on Microsoft, but one of the reasons that the Microsoft platform is used by so many people around the world is that Microsoft products often have excellent documentation. I often find that open source ‘products’ are technically superior, but are often much harder to use, because they’re built by a community, for free, and very few people want to write documentation for free. Combined with the work that Tilde is doing on Cargo, Mozilla is investing a significant amount of effort and dollars into ensuring that Rust will be a fantastic platform for those developing on it. Since I love Rust, this makes me very, very happy.

Forty hours a week is a significant amount of documentation, and I have a lot of work in front of me. But my first area of focus will be on the area of Rust’s documentation that’s the most weak, and simultaneously the most important: the tutorial. I tackled the first tip of that iceberg with my 30 minute introduction, and I’d like to tweak it too. The main tutorial, however, is the first place where people go to really learn about Rust and how it works. And the current tutorial is largely the same as the 0.5 days, back when I first learned Rust. It suffers from receiving patchwork contributions from a variety of people, rather than having one unifying vision. It’s also much more of a list of features and how to use them than a coherent tutorial.

I’m really excited to get to work. Let’s all make Rust 1.0 a fantastic release.