Finding the right tech writing voice
One of the fundamental goals of technical writing is the removal of idiosyncratic writing so that a reader cannot tell which writer produced their documentation. For a great many technical projects, you will be a contributor to technical documents and user manuals, and so it’s important that the document style remains consistent and coherent when all of the contributions from other writers are brought together. For this reason, there are a number of considerations when thinking about style and voice in a user manual.
Remember to also check out my post on style guides. They’re key to this subject.
Keep it simple
To make your text as clear as possible, use simple words. However, this does not mean that your style should resemble children's books. Do not underestimate your reader's intelligence. If the correct word is a long word, then use it. Complex words don’t make the text more credible or impressive. In fact, they have the opposite effect. Complicated wording confuses your readers, and make it look like the writer doesn’t understand the subject and is trying to cover that lack of knowledge with verbosity—no matter what reading level your user may be at.
Avoid superlatives such as extreme, very or best as these are almost always subjective and completely unjustifiable. Be careful not to exaggerate the capabilities of the product. Be as short and concise as possible. Remember, a user of your product has already purchased your product, so there is no need to try and sell it to them again.
Try to avoid sentences longer than 25 words. If you can write it in fewer words or in fewer sentences, do that.
For procedural steps, try for a maximum of six words per step. Most readers skim a procedure and look at the illustrations, and often, they won’t read past commas or line breaks.
Wordiness is the only parameter that can be accurately quantified. To improve readability, be mindful of sentence length, including articles and prepositions. To decrease the word count, try the following techniques:
Reword, rewrite, and edit. Omit needless words.
Split long sentences into multiple short sentences. Remember that each sentence must be complete.
Use bullets when possible and relevant. Bullets make it easy to scan the text and to quickly grasp key ideas.
A good indication that a document needs rewording and simplifying is the use of “for example.” Rarely is an example absolutely necessary to clarify the text.
In service documentation, take advantage of tools such as Acrolinx or Grammarly to help keep sentences short and simple.
Appropriate illustrations can also help reduce the word count.
All those methods improve readability, so you can also apply them to all sentences, even the short ones.
Never be tempted to simplify and reduce text by removing articles, prepositions and conjunctions. This results only in pidgin text which readers find annoying and amateurish, and which detracts from the original intention of simplifying the information. If you translate your manuals, this is also virtually impossible to translate as each sentence has important words missing.
Address the reader directly
Wherever possible, you should address your reader directly, and use the second-person: you. This technique helps to focus the attention on the readers so that they feel more involved in what you are describing. They are after all, the person who will need the information that you are presenting and so you should speak directly to them.
Using the second person also helps you avoid the passive voice more often.
Whenever possible, write in the present tense. The present tense is concise, gives the readers a sense of immediacy, and shows that their actions correspond to an immediate reaction of the product or system. Avoid mixing the past, present, and future tense because it confuses readers.
Be objective, not subjective
As I mentioned earlier, there is no room in technical writing for opinion, so you should avoid subjective language when presenting information. Focus on presenting the facts in a neutral and straightforward way.
Avoid using emotional language. Emotional language can cloud your reader's perception of the factual information being presented. Technical writing should be devoid of emotional expressions and only present the facts.
Use credible sources. When presenting your information, it’s sometimes helpful to provide sources or references. Make sure that you use credible sources such as peer-reviewed articles, government reports, or academic journals. Sites like Wikipedia should be avoided. While they are good ports of call for quick information and finding credible source starting points, they are not themselves, credible sources due to the open-source nature of the content they display and the tendency for many contributors to be territorial in their protection of their own contributed content.
Avoid using absolute or superlative terms like best or worst. These are mostly subjective terms, often impossible to prove or disprove, and are likely to not accurately reflect the information you are presenting.
Use the active voice. Writing in the active voice helps to maintain objectivity by placing the focus on the actions being described, rather than the opinions or emotions of the writer. Active wording also contributes positively to the readability of your content and your reader’s ability to understand the content at first reading.
Avoid personal anecdotes. Just like opinion, personal anecdotes have no place in technical writing. They are distracting, often irrelevant, and will detract from the objective nature of the content.
Be consistent. Ensure that the tone, style, and terminology used in the text are consistent throughout the document.
By following these basic tips, you can remain objective and maintain credibility in your writing. Remember: the goal is to present information in a clear, concise, and neutral manner, allowing your reader to understand the subject matter more clearly and at first reading.
Be inclusive
Make sure that your text is respectful to your readers. Inclusive language demonstrates awareness of the vast diversity of people in the world. Using inclusive language offers respect, safety, and belonging to all people, regardless of their personal characteristics. When writing, avoid all direct references to:
gender
age
race
physical and mental abilities or disabilities
nationality
socio-economic variations
history
mental health conditions
Times change and inflammatory or divisive language and terms are no longer tolerated outside of creative fiction writing. Terms which were routinely used in a technical context in the past are now understood to be non-inclusive and undesirable ways of explaining concepts.
Terms such as master and slave in an engineering or computing technology context have not been used for some years now. Likewise, software terms like blacklisting and whitelisting are rightly understood to be based on an etymology that much of society no longer subscribes to and may actively find offensive.