[rust-dev] Rust's documentation is about to drastically improve

Steve Klabnik steve at steveklabnik.com
Mon Jun 16 15:10:11 PDT 2014


Hey all! I wrote up a blog post that you all should know about:
http://words.steveklabnik.com/rusts-documentation-is-about-to-drastically-improve

Here's the text, in Markdown:

Historically, [Rust](http://rust-lang.org/) 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](https://mail.mozilla.org/pipermail/rust-dev/2012-December/002787.html).
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](http://www.designinghypermediaapis.com/), but wanted
to try it out on something else before I took the time to port the
content. And so, [Rust for Rubyists](http://www.rustforrubyists.com/)
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](https://air.mozilla.org/rust-meetup-december-2013/) 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](https://github.com/carlhuda/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](http://doc.rust-lang.org/master/intro.html), 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.


More information about the Rust-dev mailing list