← Back

Assorted thoughts on documentation

Documentation is a fundamental part of software, both open source and proprietary. There are lots of methods for building great docs, and lots of examples of fantastic software with docs that just don’t help their users. Still, we know that documentation is “is highly valued, but often overlooked”. So I wanted to share what I know and how I think about documentation, and some recommendations for you (and me).

One note before we get into it: documentation for software is very different from documentation for a product.

When writing docs for software, like a reusable open source library, we need to think about how consumers of that library will use the code. It’s not about having that answer, but about giving them the tools to use the code however they want.

What makes good documentation

This is the big question, and I’m going to separate it into three parts: content, tooling and discoverability.

Ultimately, we write documentation to remove the barrier of entry for people who may want to use our code. Ignoring the benefits of marketing or branding, the goal for docs is to help people use the thing.

I’m not an authority on what makes docs good, but I’ll be sharing some pretty clear opinions. Feel free to disagree 😗


I want to start here, because you can have the most features, the best tooling, all the bells and whistles - but if your content isn’t helpful, your docs just aren’t going to be good. So what makes content “good”? I think it comes down to focusing on what users want to accomplish. Most people don’t need to see the entire API surface - they have a goal in mind with your library and want to get there with as little friction and ambiguity as possible.

Prioritize use-case-driven examples

Users approach your library with a problem they’re looking to solve. Put the clear “here’s how to do the thing” information first.

This is tricky in practice, because it extends into API design - documenting something complex in nature is going to make for complex documentation. So when you’re writing docs, try to take the perspective of someone who doesn’t know anything about your library, why it exists or how it works - only what it does.

For example, let’s say we have a library called math. It exposes four methods: add, subtract, divide, and validate. That last one, validate, is used in the first three to validate the arguments passed to each method. We can assume that most users don’t need to see that method right away when looking at the docs. They have a problem, like “math is hard” and want to solve that problem, not absorb the complexity of your library.