Documentation should be concise, consistent, and simple

No readers like this yet.
Typewriter keys

April Killingsworth. Modified by Rikki Endsley. CC BY-SA 2.0.

"Words mean things" is one of my favorite expressions. I often use it in jest, but it's an important consideration when writing documentation. I'm normally one to sling words around with great artistic flair, but when it comes to writing technical documentation, I've become more deliberate in my wording. I don't know when this habit started, but I've noticed over the years that I have grown increasingly careful in how I use words. This article introduces three considerations and accompanying resources that you can keep in mind as you write.

Technically-savvy writers have a habit of writing like they're technically-savvy. Unfortunately, the reader isn't always as savvy, particularly if they are new to the project. Simple, unambiguous terms are preferable, with explanations of new or topic-specific terms. The IEEE Professional Communication Society has excellent guidance on using clear word choices.

Consider someone who has never used a computer as an extreme example. Getting used to the idea that a "click" involves the mouse (or trackpad) and a "press" involves the keyboard might take a while to get used to. If the documentation starts using those terms interchangeably, the reader may become confused. More experienced readers will be able to figure out the correct action from context, but the inconsistency can be jarring to someone just learning their way around the basics of computer use.

There's another advantage to proper word choice: The less time your reader has to spend figuring out what you mean, the more time they can spend on what you're trying to say. If your documentation has consistent word usage and others have consistent word usage, too, the life of your readers gets a little better. Microsoft has a comprehensive glossary of user interaction terms.

Consistency in word choice isn't just helpful to your readers, it's helpful to your translators, too. The more consistent the strings are, the less effort is involved in translation.

Speaking of translation, simpler words reduce the number of times your translators have to go look up a word before finding the right translation. Holding yourself to commonly used words also helps you explain concepts in a way your readers are more likely to understand. The XKCD comic Up Goer Five is a prime example. The Oxford 3000™ word list is a great list of commonly used words. Of course, using simpler words often means using more of them, so being simple and being concise are often at odds. If you know your audience, you can strike the appropriate balance.

So remember when you write: Be concise, be consistent, and be simple. Words mean things.

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.

7 Comments

One other point about documentation is that it needs to explain how to use something (software, hardware), not what all the buttons do. For example, how to I use my new boom box with CD is not the same as a user guide that goes on and one about the buttons, the modes, etc. People what to know how to tell the time, not how the inner working of the clock behave. Most of the user documentation for Linux apps seem to be focused on the buttons and modes, not on telling the user how to actually use the app.

That's a great point. There's a use for "here's a giant list of every possible option", but that's as an appendix to "how to use this thing!"

In reply to by dave (not verified)

To add to the translation advice - much of today's translation is done initially by machines, and the translator comes in to verify/fix any issues. Consistency not only in word choice but phrases saves $$ in the long run as the machine learns the phrase and can then translate every time that phrase repeats. (Not using exact localization terminology here but hope folks get the idea).

There is also a growing trend to have the writers involved in the UX/UI for apps as well, to help get around that need to define every button. With contextual help built into the app, the user can right-click or hover etc to get that instant 'button' definition. That leaves the docs to fun things like 'how to use this thing!" :-)

Good intentions and some good advice here but some clarification needed. There is a real and important distinction between simple language and simple documentation.

Documentation should be clear and straightforward. And there are many benefits to using simple language (often referred to as plain language) in documentation and other writings. However, this doesn’t mean that the documentation itself needs to be simple. Sometimes documentation should be complex - include complicated information. The simplicity (or complexity) of documentation should vary based on the audience and the purpose of the documentation.

Writers should understand the needs and knowledge of their audience and then write appropriately. For example, an effective admin guide for experienced engineers installing software would be written differently than that of a guide for non-technical end users of that same software. Skilled writers should be able to evaluate their potential readers (perform audience analysis) and adjust their writing accordingly.

There is a lot of information available about plain language. For me, I find the acronym KISS - Keep It Simple Stupid – is serve a good reminder and to be generally good advice for any writer. Don't overwrite or provide overly complicated information. Be direct and straightforward in your documentation.

For documentation, I've always recommended following the 4 Cs. Correct - Clear - Concise - Consistent. There are variations to this - sometimes including comprehensive and other Cs. The best writers I know are constantly challenging themselves.

Thanks for the comment, Mary. This is great advice (it might be a good article on its own if you expanded on it a bit). I agree that knowing and appropriately targeting the audience is key.

In reply to by Mary Arrotti (not verified)

Simple note about terminology: writing about "glossary of ...terms" is a tautology (repeating the same term) since _glossary_ is a list of terms...

In reply to by bcotton

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