rust-doc-days-announce.md

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.

To that point, we (the [quasi-official Rust docs team][#rust-docs IRC channel]) have organized Rust Doc Days.

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.

What makes documentation better?

We have some objective criteria on how documentation can be made better. You can find the initial criteria at Rust documentation guidelines and RFC 505: API comment conventions. If you don't like reading long things, the TL;DR is:

• 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:

• UUID
• bitflags
• unix-socket

The Details

Which Days Is This?

June 24 and 25, 2016

But Which Timezone?

• Between 7:00 AM GMT on June 24 and 7:00 AM GMT on June 26.
• Between 3:00 AM Eastern on June 24 and 2:50 AM Eastern on June 26.
• Between midnight Pacific on June 24 and 11:59 PM Pacific on June 25.

You can use this handy Greenwich Mean Time converter for your own timezone.

How Do We Collaborate?

If you want to collaborate, you can find us over in the [#rust-docs IRC channel].

There's a Documentation Team?!

Yeah, we meet every Wednesday at 20:00 GMT in the rust-docs IRC channel.