Mar 24 2017

One of Rust’s major goals this year is to provide mentoring at all levels of the project. This is a goal I’m very on-board with. There’s lots of ways to get involved with Rust, but I’d like to talk about the bit I’m most involved in: documentation.

There’s many ways to contribute to Rust’s docs. Some people contribute occasional PRs, some people end up contributing a lot. No matter what your interest, I’d like to help. But before I get into those details, why should someone get involved with documentation? I have my own reasons, but I also have a pitch for you:

Working on documentation is a fantastic way to learn something in a deeper way.

In order to document something, you have to understand it, even if only a little bit! It’s a good excuse to dig into the details. And I’ve found that many people are eager to help explain something to you in return for you writing that down and synthesizing it into documentation.

If that sounds intriguing to you, let’s talk! There’s a number of different ways to do this, and I’m interested generally in helping anyone work on Rust’s documentation, in any form. However, if you don’t have something in mind, I do have a suggestion.

Back in October of 2015, I made a big GitHub issue to track giving the whole standard library documentation a once-over. I then made sub-issues for each main module. Slowly, myself and others have been knocking them out, but there’s still a number of issues open.

Today, I went through all of the remaining ones, and made fine-grained bullet points of what needs to be done. I’ll admit that some of them may not be as explicit as they could be, but it at least gives a starting point to talk about. Here’s all the sections that are currently open:

• convert
• ffi
• macros
• thread
• sync
• str
• ptr
• process
• os
• ops
• net
• hash
• fmt

Some of the work that needs to be done is very small: add a link here, re-word a sentence there. Other bits are large; “this whole thing needs re-written.”

So here’s my pitch to you: have you ever wanted to learn a bit more about Rust? Do any of those names sound interesting to you? Maybe you’ve wanted to learn a bit more about threads in Rust. Check out that ‘thread’ issue above, poke around, learn some Rust, and then let’s make the docs better! We can work together on the issues, through email, or on IRC. Whatever works. Maybe you’ll find it as addicting as I do. And I find that people who are non-experts write way better docs than experts. So don’t worry about that!

Worst case, you’ll have learned a bit of the standard library a bit better, and that’s always a good thing, too.