Recently, I was searching for a good resource on how to write technical instructions.
What I was searching for was simple pointers on technical language including:
- Sentence Structures
- Complexity of Words
Everything I found when Googling “writing technical instructions,” or “how to write clear instructions,” was long and over-complicated. Most articles ended up being WikiHow-style, where they listed required sections like ingredients/requirements. These resources, though valid for things like recipes or how to fix something mechanical, lacked the flexibility to be applied to technical tasks. They also lacked the specifics that I was searching for – the actual language mechanics.
So here are the best practices I’ve come up through my teaching and writing experiences at work and through freelance opportunities…
Tense, Voice, Tone
The tense, voice, and tone you write with should establish you as a professional. Unlike an essay or editorial, you should be writing in second person.
Think about how you would explain how to do something if you were in-person: You would speak in short sentences, directing the individual on what to do. Your language should also be active, not passive. Passive sentences tend to be more complex and “wordy.”
“Passive voice sentences often use more words, can be vague, and can lead to a tangle of prepositional phrases.”
– The Writing Center, University of Wisconsin-Madison
Bad: One should download a backup prior to updating.
Good: Download a backup before updating.
You should also avoid grammatical/spelling errors as those will hurt your credibility as an expert and can even be distracting to some readers.
With any form of instructional/educational writing, avoiding unclear phrases or wording is essential. It’s important to use the most clear, audience-appropriate terminology in your technical instructions.
The two biggest adversaries to clear, direct technical writing are:
- Filler Words/Phrases
Filler words include phrases like, “in order to,” “such as,” “essentially,” and “basically.” They’re words that don’t add any meaning to the sentence. Phrases like “in order to” can be avoided altogether if your article title already states the purpose of the steps/instructions. For example, if your article was “How to Set Your Profile Picture,” you wouldn’t need to start the first sentence off with “In order to set your profile picture.”
Jargon is more of a gray area when it comes to technical writing. You should use the accurate terminology from the field, but try to provide definitions or sources any time a lesser-known term is used. For example, if you are writing an article explaining how to forward a domain name, you might want to define “domain registrar” for the readers.
The Right Words
- Short words
- Common words
- Words of definite meaning
- Words of vivid impression
The idea is to help us stay simple with your messaging and communication. It’s not about sounding intellectual or using big words. It’s about getting your thoughts across, succinctly and passionately, so that people can understand it and be able to visualize it.
– Happy Melly’s Speech Writing Rule #3: Use The Right Words.
Instructions need to be easy to scan. Chances are, your readers will not be reading every word that you write because they are typically under a time constraint.
Some methods to break up blocks of text include text treatments (bold, italics, font variations), use of images, blockquotes, horizontal rules, links, and lists.
Lists can be especially helpful with instructions. It’s important to understand the difference between an ordered/numbered and an unordered/bulleted list. Numbered lists should only be used when the order of the steps would change the outcome. If you start off writing a numbered list and get to a couple steps that don’t need to be done in a particular order, specify that by grouping those items together under one number. For example, if you are writing instructions for updating a plugin and have a section about running backups of the database and files before updating, group the database backup and file backup together under the same step.
Section headings are vital to the flow of the article. Any time you find yourself writing more than a couple paragraphs on a particular section of the instructions, you should consider adding a heading or subheading.
Another important aspect of your writing to focus on is consistency. In the tech world especially, there are various things we can say that have the same meaning. “Login,” “Log-in,” and “Sign In” have the same meaning, but can be distracting or confusing if they are used interchangeably.
- Use second-person, active language.
- Avoid grammatical/spelling errors.
- Avoid filler words/phrases and jargon.
- Use lists to break up blocks of text, but pay attention to list types.
- Be consistent with your terminology to avoid ambiguity.
– Here’s an example of really clear, helpful technical instructions that I used recently.
Example from WikiHow:
– I would go one step further with this and just say “Push the lever.”
Technical Instructions vs Documentation
For the purpose of this blog post, I’m defining “technical instructions” as a form of end-user documentation that is available to users of a product/service. In this way, I’m attempting to differentiate between writing technical instructions and writing “documentation,” which has its own unique requirements.
Closest/Most Similar in Search
– Focuses on having a clear direction before starting, segmenting audience(s), being detail-oriented, and using sources.
– Focuses on content strategies, such as including screenshots, framing new release information by comparing versions, and being proactive.
– Sightly geared towards using documentation as a selling proposition. More focused on code documentation than end-user instructions.