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

Brian Anderson banderson at mozilla.com
Mon Jun 16 15:17:44 PDT 2014


Thanks, Steve! This is going to do wonders for our fit and finish going 
into the home stretch for 1.0.

On 06/16/2014 03:10 PM, Steve Klabnik wrote:
> 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.
> _______________________________________________
> Rust-dev mailing list
> Rust-dev at mozilla.org
> https://mail.mozilla.org/listinfo/rust-dev



More information about the Rust-dev mailing list