5 Steps to Writing Better Documentation

January 26, 2015 Kim Hoffman

Even if you’ve never had to document a feature you worked on, you’ve probably used open source software in need of community-contributed documentation. You might even have a project of your own that’s begging for a little prose. Follow these five rules to avoid some of the most common pitfalls I’ve seen in technical documentation.

1) Avoid the passive voice.

We’ll never know who made those mistakes.

The active voice places the actor, otherwise known as the subject, before the action of a sentence:

“I made a mistake.”

Contrast that with the passive voice, which puts the object (receiver) of the action first. The passive voice often leaves the subject in total obscurity:

“Mistakes were made.”

There are few occasions in which the passive voice is necessary. At best, it adds words (this is not a desirable quality; see Rule 5). At worst, it reveals the writer’s weak grasp of the technical content.

Not sure if you’re a passive voice perpetrator? Inspect sentences that use the preposition “by” or verb phrases that include a form of “to be.”

2) Respect your audience.

Don’t worry, a trained monkey could do this.

Plenty of technical documentation seems to expect its users to be a frightened, cautious bunch, in need of frequent encouragement. Describing a procedure as “easy” or “simple” might seem reassuring, but resist the temptation to use these words. Many users turn to the docs for the first time because they already hit a wall with the product. Nobody wants to hear that they’ve spent time and frustration on something they should have found “simple.” If the reader could perceive it as condescending, leave it out.

3) Make it skimmable.

Users don’t read (they’ve got better things to do).

It’s safe to assume that most of your readers skim your documentation. This is technical documentation, not the great American novel: your audience wants to find specific information quickly and get back to using the product. Make it easier for them with a few techniques:

  • Break your content into digestible chunks and use descriptive headings.
  • Tailor your formatting to your content. If a user must complete steps in order, stick to an ordered list. If you have a lot of detailed information to share, consider whether a table suits the occasion. Use screenshots whenever possible.
  • Always preview what you’ve written in its final form and consider the page from a visual perspective. If you see a chunk of text that looks meaty, consider it a red flag. Chances are there’s a better way to present the information.

4) Lose the adverbs.

They’re usually really unnecessary.

Adverbs seldom add meaning. If they have nothing to add, cut them. Be ruthless. Cut other useless words while you’re at it.

5) Less is more.

Stay relevant.

Define the scope of your content before you begin writing. You should be able to answer the question, “What will a reader learn from this topic?” Be specific. In most cases, keep your topic narrow so that your reader doesn’t have to hunt through reams of irrelevant information.

Once you’ve written a draft, read it. Consider what every paragraph, sentence, and word brings to the table. If you can’t figure out why a sentence is relevant, your reader won’t know either. If a word doesn’t add meaning, it will only obscure your point. Cutting the cruft forces you to be clear about your subject matter.

The next time you have to figure something out the hard way because the docs don’t have an answer, don’t hesitate to jot down a few notes. Your co-workers/co-contributors might be grateful for your clear and confident documentation!

About the Author


Monitoring Pivotal Cloud Foundry Health and Status: Hybrid Models, KPIs, and More
Monitoring Pivotal Cloud Foundry Health and Status: Hybrid Models, KPIs, and More

Pivotal Cloud Foundry provides a new way of managing development, deployment, and operations. As companies ...

Re-Architecting Genomics Pipelines to Handle the Rising Wave of Data
Re-Architecting Genomics Pipelines to Handle the Rising Wave of Data

Genomic data is quickly becoming a central part of the next generation of medicine. The future of treatment...


Subscribe to our Newsletter

Thank you!
Error - something went wrong!