The State of Rust Docs

Every week I hop on IRC and meet with an unofficial Rust documentation team. Our goal is to take a look at documentation across the Rust ecosystem and to figure out how to improve the general state of things. Our work covers a lot of space and includes documentation tooling, centralized documentation, and reviewing the state of API & library documentation.

Documentation - it drives developers crazy

Documentation – it drives developers crazy

My Personal Goals

As a newcomer to Rust, I’ve spent a lot of time looking at Rust’s library documentation. Good documentation across a language and its ecosystem makes life easier for new developers. Clear documentation and helpful examples make it easier for developers to get into a language. Writing documentation doesn’t come naturally to many developers.

I want to remove as much friction as possible around writing good documentation.

It’s not easy to write good documentation. I’ve been working with Jonathan Turner to create documentation to help developers write better documentation. We’re still in early stages, but our drafts are coming along nicely.

What We’re Talking About

In September of 2015, Steve Klabnik started the thread Let’s talk about ecosystem documentation to get a general overview of the ecosystem. Steve’s initial post provides a breakdown of how we’re judging documentation; there are four points to consider:

  1. The First Contact – What is this library and why should I use it?
  2. The Black Triangle – How do I get started with this?
  3. The Hairball – How do I go from beginner to intermediate?
  4. The Reference – Complex documentation for advanced user

It’s been over six months since the initial ecosystem forum thread was started; since we’re working on building better documentation, I decided it was time to take a look at where the community’s documentation stands today.

The State of Community Docs Today

Very little has changed since the original “Let’s talk about ecosystem documentation”. The libraries with good documentation still have good documentation. The libraries with bad documentation or no documentation still have bad or no documentation.

Some documentation guidelines were accepted in RFC 505 – API Comment Conventions, but these are just conventions about what form any documentation should take. You can think of RFC 505 as a style guide rather than a guide to writing new documentation. The More API Documentation Conventions RFC is still in review, but it replaces RFC 505 and adds additional guidelines around documentation structure. This is a step in the right direction, but there’s a lot of work to be done, especially if the discussion around the RFC is any indication.

Reviewing Community Documentation

There’s more to documentation than just guidelines and RFCs. I looked at the top 20 Rust crates by total downloads to see what the state of documentation is today.

As I reviewed the crates, I used the four documentation criteria (outlined above and in Let’s Talk about Ecosystem Documentation). I also viewed the documentation through the eyes of an inexperienced Rust developer. As I looked at the documentation, I tried to imagine how I’d feel encountering a particular library for the first time, how I could use that library in my own code, and how I’d be able to master the nuances of a particular library. This wasn’t much of a stretch since I usually have no idea what I’m doing.

Documentation is a mixed bag today. Some libraries have good documentation and tutorials. In these cases, it’s clear that the developers have considered who would be using their library. Good documentation needs to be able to make a new developer feel comfortable with an unfamiliar technology. Good documentation also needs to provide a path for experienced developers to dig into the inner workings of a library and understand the finer points of how that code works.

Three outstanding crates were Diesel, the log crate, and the collections libraries in the standard library:

  • Diesel.rs has detailed tutorials that walk a new user through working with Diesel. API documentation provides additional details about the guts of Diesel.
  • The collections libraries have helpful documentation that would allow a user to choose the right collection for a given purpose and immediately jump to that collection’s documentation.
  • The log crate immediately tells the reader what they’re looking at and provides a brief code sample.

Other libraries have more limited documentation. In many cases, the documentation is simply bare bones auto-generated documentation that’s generated by cargo. If the authors haven’t thought to provide a good landing page in their auto-generated documentation, it won’t be present wherever documentation is deployed. While good documentation sometimes exists, it takes a few clicks to find the right macro or module that has the right documentation.

There is one exception: wrapper libraries like libc and winapi. This type of library is a wrappers over *nix or Windows system calls. If I’m poking around in OS specific constructs, it’s not Rust’s job to tell me what’s going on. I need to go find documentation for my operating system.

In many cases, projects have a decent landing page and meet that beginning step of “How do I use this the first time?” Beyond the first view, the documentation falls down – public methods are not documented or else the documentation reads like auto-generated JavaDoc fn fizzbuzz: it buzzes the fizz.

Documentation Issues

Most Rust projects are hosted on GitHub. It’s possible, and relatively easy, for users to create documentation issues when they encounter a problem with documentation.

While performing research for this article, I only found a handful of documentation specific issues in GitHub. These issues were all directly tied to a pull request that corrected existing documentation. They weren’t issues asking for additional documentation or requesting clarification; these issues were created by existing users who know enough about Rust and the relevant tooling to find errors, fork a repository, fix the error, and then send a pull request back to the original repository.

New users may not even know that they should submit an issue for better documentation. Or, if they do know, they may be too timid to submit an issue. We can’t rely on users to create issues for documentation – new users are the ones who get the most initial value out of documentation. But new users are also the most likely to abandon a library, tool, or language if they can’t find good documentation

The Current State of Documentation

Right now, the overall Rust ecosystem’s documentation is spotty. There are a few stand out crates, but there isn’t consistent documentation across crates. There’s a lot of work to do to make sure it easier for developers to understand what it takes to create good documentation and to provide guidelines to help that happen.


Driving” by John Shepherd licensed with CC BY-2.0

 

7 Comments. Leave new

  • Jacob Chae
    2016-05-04 16:43

    Awesome article! I am very new to Rust, but I have to say that the amazing documentation is definitely one of the things I like most about it. You mentioned an irc chat where the docs are discussed. What is the best way to get involved in that?

    Reply
    • Hi Jacob, we hangout on the Mozilla IRC server (irc.mozilla.org) in the #rust-docs channel.

      You can find a list of the Rust IRC channels in the A List of Rust IRC Channels thread.

      Reply
    • Fun question, actually – how would you like to get involved? Do you want to write more docs? Write code to help with doc tools?

      Reply
      • Jacob Chae
        2016-05-04 20:42

        I would be interested in both actually. Is there a specific time people meet in the docs channel?

        Reply
        • Many of us loiter in the channel, but the regularly scheduled committee meetings are at 20:00 GMT every Wednesday. The channel’s status message has links to the IRC history as well as previous meeting minutes.

          Reply
          • Jacob Chae
            2016-05-04 20:46

            Awesome, thanks for all the info. 🙂

          • Any time! We’ve got a lot of interesting work coming up in the documentation space. It’s especially interesting since there aren’t a lot of tools and the ecosystem is young. We get to shape the way documentation will work going forward.

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