Announcing Rust Doc Days

Documentation is an important, but overlooked, part of programming. While we can’t make you write documentation, we’re hoping that we can help you remember that good documentation means people are more likely to use the tools that you build.

What is it?

During Rust Doc Days we’re going to make a conscious effort at improving documentation in the Rust ecosystem. For two days (June 24 and 25) we’ll be working on crates in rust-lang and rust-lang-nursery to improve documentation.

How do I take part?

Taking part is easy, between 7:00 AM GMT on June 24 and 7:00 AM GMT on June 26 make a pull request against one of the crates in rust-lang and rust-lang-nursery that improves the documentation. You don’t have to do a sweeping re-write of the documentation, just make it a little bit better.

The main crate documentation page should offer a short explanation of what it does and why.

The main crate documentation page should also have concise examples.

Every public API should have both an explanation and an example.

If you need to have a longer example of your crate, use the examples folder.

During Rust Doc Days, just make documentation better: write short examples, clarify explanations, create example programs. The goal isn’t to produce perfect documentation; the goal is to make documentation better a little bit at a time.

Got Any Suggestions?

Yeah, we sure do! The crates in rust-lang-nursery have solid code, but the documentation needs some love. A few of the crates that could do with some affection are:

Alas, my ‘Quick Add’ tip isn’t applicable here. Since it’s a multiday event. In the same vein, an iCal entry would’ve been useful (and of course more portable across calendar apps than a textual description). When you’re busy working you’ll have to be reminded of such remote volunteer events.

Yeah, no problem of course. 🙂 Having an iCal link or Quick Add parsable snippet ready just speeds it up.

Question, what should volunteers do to prepare for optimally participating in the Docs Days? I have just too limited time on my hands to deeply get into Rust before that event, I think. It would be a pity if outsiders have to study too much material to do anything meaningful within a few hours after the push has started. Currently in terms of doc writing guidelines and rules I’m only finding https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#writing-documentation, but I remember Guillaume Gomez having published some documentation best practices doc somewhere ..

Some small comments just relevant to your blog. Is there actually a way to cancel notification of follow-up comments? Should the off-brand porn etc. still pass through? 😉 Also, perhaps a social login button would make responding and limiting abuse a bit more intuitive?

To prepare for the Rust Doc Days, just take a look at the crates in rust-lang-nursery and see what interests you. There are also some open issues in the Rust GitHub issues list, those could be worth looking into, too.

Guillame has an RFC open for error formatting, you could hop in the IRC and ask him – I don’t recall what else he would have produced. There’s also the guidelines I mentioned and then RFC 505.

Social sign-ons are great, but they use things like disqus, which means I have to depend on another service to be up and running. The barrier to entry to sign up for a social account is remarkably low, so that wouldn’t really stop anything. Akismet does a fairly good job of detecting spam, but occasionally new techniques get through. Plus, it’s lightweight and runs on my host. And, honestly, I really do delete comments that I just don’t like.