"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.
7 Comments