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
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:
- The First Contact – What is this library and why should I use it?
- The Black Triangle – How do I get started with this?
- The Hairball – How do I go from beginner to intermediate?
- 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 barebones auto-generated documentation that’s generated by cargo . If the author’s haven’t thought to provide a good landing page in their auto-generated documentation, it won’t be present on https://doc.rust-lang.org . 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 .
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.