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) have organized Rust Doc Days.

Writing documentation is fun!

Writing documentation is fun!

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:

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.


writing” by ThroughKiksLens is licensed with CC BY-SA

10 Comments. Leave new

  • A tip, could you provide such event details in a Google Calendar parseable (and concise ;)) format:

    What: Rust Docs Days
    When: June 24 7:00 AM GMT – June 26 7:00 AM GMT
    Description: https://facility9.com/2016/06/announcing-rust-doc-days/

    Such a snippet can be pasted into Google Calendar ‘Quick add’. It’ll even do the timezone calculations for you.

    Reply
  • Any idea what happens to comments on here? I didn’t get a confirmation web UI indication/e-mail so far and the comment hasn’t appeared. I used a plus sign in it, is that the issue?

    Reply
    • I manually approve comments so my blog doesn’t become a spam farm for off-brand medication and low budget pornography.

      Also so I can delete comments I don’t want to look at 😛

      Reply
  • 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.

    Reply
    • So… You got it added to your calendar OK?

      Reply
      • 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?

        Reply
        • 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.

          Reply
  • FYI:
    ‘You have requested to manage your subscriptions to the articles on facility9.com. Follow this link to access your personal page:’ and then no link.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

Fill out this field
Fill out this field
Please enter a valid email address.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Menu