Words mean things: Documentation considerations

Documentation should be concise, consistent, and simple

Posted 29 Feb 2016 by 

up
59 readers like this
Documentation should be concise, consistent, and simple
Image credits : 

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.

Doc Dish

This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us.

7 Comments

dave

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.

Vote up!
3
Vote down!
0
bcotton

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!"

Vote up!
0
Vote down!
0
Sandra McCann

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!" :-)

Vote up!
1
Vote down!
0
Mary Arrotti

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.

Vote up!
2
Vote down!
0
bcotton

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.

Vote up!
0
Vote down!
0
Marie-L. Flacke

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

Vote up!
0
Vote down!
0
bcotton

I am humbled. :-)

Vote up!
0
Vote down!
0

Ben Cotton is a meteorologist by training and a high-performance computing engineer by trade. Ben works as a technical evangelist at Cycle Computing. He is a Fedora user and contributor, co-founded a local open source meetup group, and is a member of the Open Source Initiative and a supporter of Software Freedom Conservancy. Find him on Twitter (@FunnelFiasco) or at