How to Write Documentation ​

If you want your code to be useful to other people, you need to document it well.

Identify Your Audience ​

Before you start writing, you need to identify your audience: Who are you writing documentation for?

Having a good understanding of your audience will help you write clear and relevant content that maps to their needs. Content that maps to the audience’s needs leads to better comprehension and less confusion and frustration; it presents helpful information that explains confusing tasks and concepts, and anticipates where their challenges might occur.

If you’re not sure who you’re writing for, or if you think the answer is simply “our customers,” try digging a little deeper. Use questions like these to think about your audience:

• Is the audience inside your company, or are you writing for external customers?

• Are they developers?

  • What kind of developers are they? Do they work on backend, web, mobile, or other components?

  • Will they contribute to your code or just use it?

• Are they data scientists?

  • What kinds of tools, languages, and libraries do they use?

• Are they non-technical users?

  • Will they understand basic technical tasks?

  • How much technical terminology do they need to understand in order to do their job?

Code Talks to Computers, Docs Talk to People ​

Code can never tell you why it was written or how to use it. People require communication outside of code to understand the social context within which it exists and has purpose. Documentation is the practice of writing the social context down so you can communicate it to people at scale and facilitate successful adoption of your code. Another way to think about documentation is as the interface between your code and other people.

But Nobody Likes Writing Documentation ​

If you feel this way you are not alone. Writing documentation doesn't always feel like a priority when you also need to code. Good documentation makes code more reusable and understandable, so the code and other coders will thank you for it. Writing documentation at the same time as you write code can make it a more manageable and enjoyable task.

Writing Docs Helps You ​

Writing documentation is a great way to think through the details of a technical subject. It can help reframe issues in your mind that lead to insights about the project or areas for improvement that you may not have thought of before. It can even help in the planning stages of a project or new feature. Some people even practice Documentation-Driven Development!

Writing Docs Helps the Community ​

Documentation is the first place most coders go to try out or learn about a new project, or when they come across an issue or try solving a new problem with a project they already are familiar with. That means that documentation contributions can make even more of a positive impact on a project's community than contributions to the code.

GitHub's 2017 Open Source Survey found that the biggest problem encountered in open source was "incomplete or confusing documentation." Their top insight from the survey was this:

Documentation is highly valued, frequently overlooked, and a means for establishing inclusive and accessible communities.

Any contribution (small or large) is always greatly appreciated by the project maintainers and its users.

Aspirational Documentation ​

Some projects with documentation that I try to learn from:

• VueJS
• SQLite
• FreeBSD
• Bunjil
• Docker
• AWS

Ideal Documentation ​

In my opinion the ideal documentation usually has 3 components.

1. The Why / Goals: the context and goals of the project

2. The What / API / Reference: detailed technical documentation of the programming interface

3. The How / Examples / Guides: example-based guides for accomplishing specific tasks

The Why / Goals ​

• What was the motivation for this project being built in the first place?

• What are some similar projects and how are they different?

• What types of projects would this project be a good fit for, and when might something else be better?

Usually this is best answered by the authors of the project. If it's possible, it might be helpful to get their point of view on this to add to the documentation if it's not there already. Sometimes people leave out explaining where the project might not be the best fit, but it is very useful and appreciated by users.

The What / API / Reference ​

• What are the different high-level components and how do they fit together?

• What are the different low-level data types and functions and what do they do?

• There is usually some of this already. If there isn't any, it can be very difficult to get started at all. This can be a good place for suggesting changes where things are unclear to you as you are learning how to use the project. Maintainers can sometimes be picky about this area of the documentation since it's viewed as the authoritative source of information, but it can be a good opportunity to learn about the nitty-gritty details of the project.

The format of this type of documentation is often language-specific, since most languages come with some kind of built-in system for generating docs from comments in the source code. That is usually the format that people coding in that language expect to see this type of documentation in.

The How / Examples / Guides ​

• How do you install the project and get some basic code running?
• What steps do you take to build a simple application using this project?
• What steps do you take to address common problems the project addresses?

This is usually the area with the most room for improvement and easiest for someone new to the project to jump into.

This part of the documentation holds a user's hand and walks them through each step in a clear way, leading them to the nirvana of working code that solves a real issue (or it's clear how it can be applied to one).

You can write this type of documentation by building a small thing using the project and take careful notes at every step about what you're doing, so that somebody else could follow along by just copy-pasting. You can easily turn this into a guide that takes users from total beginner to a small win and an aha-moment.

Most people coming to a project are total beginners in it, so writing for other beginners from a beginner's perspective is immensely valuable. People with more experience in the project may actually have trouble seeing from a beginner's perspective so they usually really appreciate this type of contribution. I think this type of documentation goes a long way in making projects more approachable.

Minimum viable documentation ​

A small set of fresh and accurate docs are better than a sprawling, loose assembly of “documentation” in various states of disrepair.

Write short and useful documents. Cut out everything unnecessary, while also making a habit of continually massaging and improving every doc to suit your changing needs. Docs work best when they are alive but frequently trimmed, like a bonsai tree.

This guide encourages engineers to take ownership of their docs and keep them up to date with the same zeal we keep our tests in good order. Strive for this.

Identify what you really need: release docs, API docs, testing guidelines. Delete cruft frequently and in small batches.

Gather feedback ​

Gathering feedback is a key part of writing good documentation and developing an ongoing content strategy. Ask for input, both internally and externally, on your documentation content and structure early on in the process.

Work with engineers on your team, or another team like technical support, to perform quality assurance. Have them validate each step in your documentation. Next, ask for feedback from your audience through interviews, surveys, emails, ratings, or other methods. Use this feedback to improve what you’ve written and identify new topics to write about going forward.