10 tips for making your documentation crystal clear

542 readers like this.
Typewriter keys

Bob Doran. Modified by Opensource.com. CC BY-SA 2.0.

So you've some written excellent documentation. Now what? Now it's time to go back and edit it. When you first sit down to write your documentation, you want to focus on what you're trying to say instead of how you're saying it, but once that first draft is done it's time to go back and polish it up a little.

One of my favorite ways to edit is to read what I've written aloud. That's the best way to catch awkward phrasing or sentence structure that might not stand out when you're reading it to yourself. If it sounds good when you read it aloud, it probably is. If your documentation happens to include instructions, you can watch someone try to follow them. This provides good feedback on what steps are missing or unclear, particularly if the person is unfamiliar with the subject.

It is also helpful to have someone who is a good writer read and edit what you've written. My favorite benefit of writing for Opensource.com is the fact that I have excellent editors to review my work before it goes live (Read: 7 big reasons to contribute to Opensource.com).

Here are ten things to look for as you clarify your documentation.

Active vs. passive voice

You should prefer the active voice in most cases. It's okay to be direct. How do you check for passive voice? Insert the words "by zombies". For example, it is much clearer to say "If you click 'yes', you will delete your data" instead of "If you click 'yes', data will be deleted." Apply the zombie test to these two examples:

  • "If you click 'yes', you will delete your data by zombies."
  • "If you click 'yes', data will be deleted by zombies."

In the first example there is no doubt that you are the actor. The second example shows that there is room for misinterpretation. Make it very clear what actors perform actions.

Eliminate jargon

Some jargon terms are unavoidable, but for the sake of clarity you should avoid them as much as possible. Linking to the definition of a term the first time you use it is acceptable, and you should also write your own brief definition. You don't want to rely on the availability of external sites, or make your readers jump through too many hoops to understand your documentation.

Check for common mistakes

Question everything you think you know, and take advantage of having the world at your fingertips and look up everything. For example, "e.g." means "for example" and "i.e." means "in other words". "Effect" is a noun (except when it isn't, as the comic xkcd demonstrates), and "affect" is a verb. Use "which" when a clause can be removed from the sentence without a change in meaning, and "that" when it cannot.

Remove dangling modifiers

You have created a dangling modifier when it is unclear which object is being modified by a word or phrase. A classic example is "Hungry, the leftover food was devoured". Is Hungry the name of the food? Add a comma after "food" if that is your meaning. If not, rewrite it to make your meaning unambiguous: "Your author was hungry and devoured the leftover food." Organize your sentences carefully; don't force your readers to guess your meaning.

Check your style guide

If your project or company has a style guide for documentation, check that what you've written conforms to it. One common mistake is the inappropriate abbreviation of company and project names.

Avoid unclear words

Do you know how many times I deleted words like "often" and "some" while writing this article? I don't know exactly how many, but I know it's a non-zero number. Use words with specific meanings. This is particularly important when you're trying to convince your reader that what you're telling them is important. If I say "Following these tips will make your writing better", that's less convincing than "Following these tips will increase financial contributions to your project by 45%." If you catch yourself using vague words, ask yourself if you really understand your topic, or if perhaps you're trying to hide something.

Check the word order

The English language does not have a formally-defined ordering structure for modifying nouns, but there is an informal structure which is described in this Tweet by Matthew Anderson: Opinion-size-age-shape-color-origin-material-purpose Noun. It's something native English speakers know, but don't know we know. Peter Sokolowski replied with advice to Put the "nounier" words closer to the noun. If that doesn't help you read the discussion to his reply, which has numerous examples and explanations.

Remove words like "just" and "simply"

Technology is not as simple as we like to pretend it is. If you tell your readers that something is simple and then they can't do it, what are they to think of themselves? Unless you're writing an infomercial for the latest must-have kitchen gadget, leave out those words.

Check your pronouns

When you say "we", who do you really mean? I have seen documentation written in what I call "cooking show style", where "Next we click the whatchamadoozit to fribble the wozulator." When you're writing in a support context it is especially important to be clear who does what. If you tell someone "We can change that setting", they expect that you will do it for them, and not that they can do it with your guidance. As a general rule, I avoid using first person (I/we) except when I am talking about myself as the author or the organization I am representing. When in doubt, refer to yourself in the third person (e.g. "The author suggests you refer to yourself in the third person"). It might sound overly formal, but it is clear.

Remove split infinitives

Don't put words in between "to" and a verb. Your documentation is on a mission to go boldly where no docs have done before. (Starship captains are excused from this rule).

Do you have other tips you love? Let us know in the comments.

User profile image.
Ben Cotton is a meteorologist by training, but weather makes a great hobby. Ben works as the Fedora Program Manager at Red Hat. He is the author of Program Management for Open Source Projects. Find him on Twitter (@FunnelFiasco) or at FunnelFiasco.com.

12 Comments

Lots of great tips on writing in general here Ben. Thank you for a great guide.

Thank you for the helpful article. My pet peeve is 'in the process of" verbing. If you are verbing, you are already in a process. So when I edit (a do a little of it for others) I can usually globally delete "in the process of". In fact, I am in the inception of initializing the process of inculcating more better writing. (Yuchh!!)

I agree. I tend to write like that, but I am also in the inception of initializing the process. I do think that "in the process of" is beneficial when the emphasis is on the process, not the verb.

In reply to by Noel H. Taylor (not verified)

If you're going to do a lot of writing, it's good to have a book like Fowler's Modern English Usage to help with proper usage. You certainly don't want to rely on how other people write to explain usage and grammar.
This business about active vs passive also applies to whatever application you might be documenting. For a time, when you exited some programs, you would get a dialog that gave choices Save and Don't Save, the latter being less clear than Discard, which many programs now use.
Although you generally don't want to load your documentation with jargon, sometimes it's unavoidable or even necessary. What you need to do is to define the jargon, maybe even put it in a sidebar or in bold print so the reader can find it easier.

The "Save/Discard" example is great. Thank you for bringing that up. I agree that jargon is sometimes unavoidable or necessary. The audience context is key.

In reply to by Greg P

If you're going to publish a guide to English grammar, try to get it right. If "Hungry" is the name of the left-over food, then the sentence REQUIRES commas, around the phrase "the left-over food". since it is an adjectival phrase in apposition. Correctly, the sentence should read ""Hungry, the leftover food, was devoured".

Nicole, thank you for reading. You are correct that I made a mistake here and I will correct it. The 11th tip is "no matter how careful you and your editors are, at least one mistake will make it to print."

In reply to by Nicole (not verified)

As someone above noted, Fowler is a valuable resource. He may be rather dated, but his article on the split infinitive is hilarious. It seems that Ben cotton, the author of this article, (note the adjectival phrase in apposition, again) falls into Fowler's category of those won't split an infinitive, without necessarily understanding why they avoid doing so.

Don't worry. I have never met a rule of grammar that I wouldn't violate. I included this because in general sentences are easier to understand with split infinitives are avoided. But if I'm being totally honest, I mostly wanted to make a Star Trek joke. Of course there are exceptions to this and other rules. When the rules are broken, that may be an indication of a needed rephrasing.

In reply to by Nicole (not verified)

Great article, Ben!

Writing tips can appear in the weirdest places. I once saw a birthday card (!) at our local supermarket (!!) that had two people on the front cover talking:

1st person: So where is your birthday party at?
2nd person: Never end a sentence with a preposition!

Inside:

1st person: So where is your birthday party at, jerk?

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.