How to write good documentation

Efficient writing is writing that delivers the most value in the least amount of time. For writing to be efficient, it must be audience-focused and contain concentrated information with a clear structure.

So how can you make your writing more efficient?

1. Know your audience.

Your goal when writing is to identify the people who will read it and then cater your writing to your readers. Before you can write efficiently, you have to know who your audience is and what they care about.

Software engineers will need different information than product managers. Investors will want different information than interns. If you can’t articulate what your audience wants, ask them. It seems obvious, but it’s an easy step to miss.

Understanding your audience will help you:

• Create value for your readers.
• Build a more compelling argument.
• Eliminate irrelevant information.

That said, sometimes you’ll need to write for multiple audiences with competing interests. How can you balance the interests of all of different audiences?

2. Prioritize common interests.

Typically, there will be at least some overlap between your audiences. You can take advantage of this fact by putting the most common interests at the top. This approach increases the chances that any given reader will get value quickly.

For example, let’s say you’re writing a project scoping document that will be read by engineers, product managers, and executive stakeholders.

A high-level definition of the project and its key metrics will likely be helpful to all readers. On the other hand:

• Sequence diagrams may be helpful for product managers and engineers, but probably not for executive stakeholders.
• API contracts may be helpful for engineers, but not necessarily for product managers.

A well-prioritized document, then, might look like this:

1. Project Overview
2. Key Metrics
3. Sequence Diagrams
4. API Contracts

3. Prioritize the most expensive audience.

The further down you bury a relevant section of your document, the more time a reader will waste trying to find it. Not every audience will have the time (or the patience) to sift through an entire document to find the sections that are valuable for them.

If we define efficient writing as writing that delivers the most value, then we have to consider the cost of wasted time when structuring our document. It’s more expensive to waste five minutes for a CEO than it is for a junior engineer, so it might make sense to prioritize the CEO’s interests in our structure.

4. Create a table of contents.

It’s hard to guess your audience’s priorities correctly.

This problem is compounded by the fact that an audience’s priorities may change over time. First-time readers may need different information than readers who are using your document often.

A table of contents makes it easier for users to find what they need quickly. As a result, it reduces the impact of misunderstanding your audience’s needs while keeping your document useful as those needs change.

5. Make your structure obvious.

The structure of your document should be obvious to any reader. This ensures your document is skimmable and makes it more likely that your reader will find what they need. For example, you might:

• Use subheadings to make it clear when you are changing topics.
• Use bulleted or numbered lists for lists longer than three items.
• Use short paragraphs (under 5 sentences).
• Use short sentences (under 25 words).

Of course, these are just guidelines. You may need to break some rules. But, if you’ve structured your writing well, your audience should know immediately when they’ve finished the section relevant to them.

6. Outsource rabbit holes.

The more information you include in your document, the more difficult it is to navigate. Every word spent defining jargon or walking through examples is diluting your document.

If you’re writing a paragraph to define a topic your audience might not even need, try linking to another resource instead. Not only will this keep your document clean, but the resource you use may even be more detailed than your summary.

7. Create separate documents for niche audiences.

It’s pretty rare that there is zero overlap between your audiences’ interests, but it does happen. If that’s the case, it would be impossible to create a single, efficient document.

Instead, you may want to consider making separate documents for each audience. While this approach may take more time, it ensures that each audience gets the information that matters to them while keeping each document focused.