25 May, 2020
by Samantha Enslen
Technical writing can be a challenge. Often, you’re exploring a new topic—say, overhead cranes that are used to move heavy items around factory floors.
First, you need to interview an expert—or multiple experts—to help you understand just how these machines work. Next, you have to synthesize that information and decide how to organize it. Finally, you have figure out how to explain that information to someone else—so they can learn how to operate a crane efficiently, correctly, and safely.
Oh, and you want to make sure they do it in accordance with OSHA standards, too.
Any mistakes you make in the instructions could literally jeopardize someone’s life. And inconsistencies, typos, or confusing prose may mean a crane operator gets frustrated with your instructions and stops reading. Or only gains a partial understanding of what you’re trying to convey.
Following best practices for instructional writing can help you avoid these problems and create clear content that readers can easily understand. Here are a few tips that any technical writer or editor should embrace.
Before you start writing, think about who your reader will be.
Let’s say you’re writing an instructional guide on insulin management systems for people with diabetes. The approach you take, and the language you use, will be very different depending on your intended audience.
Let your reader dictate everything from the terminology you use, to the sentence structures you choose.
No matter what audience you’re writing for, a guaranteed method to turn them away is to present them with a big wall of text—page after page of single-spaced text. Yuk.
Instead, think about breaking your content into small, easily digestible chunks. A good rule of thumb? If a section of text is larger than the palm of your hand, break it up.
Let’s say you’re writing a primer on creating a raised-bed garden—a type of garden where the bed sits on top of your soil, usually inside a wooden frame. It might be tempting to write cute headlines like “Ring around the Roses,” “How Does Your Garden Grow,” or “Roses are Red, Violets Are Blue.”
Don’t do it. Save the cutesy headlines for a feature story or a fun blog post.
In tech writing, each headline should be purely informative. It should let the reader know exactly what to expect in the section that follows. Your headlines in this primer might be something like this, for example:
These headlines aren’t poetic, but they’re crystal clear.
In fiction writing, the use of multiple terms for one item is acceptable—even encouraged. After all, The Odyssey wouldn’t be The Odyssey if Athena were always called “Athena.” Instead, Homer sometimes calls her “gray-eyed Athena”; other times “Pallas Athena.” She’s sometimes the “hope of soldiers”; other times “third-born of the gods,” or “she whose shield is thunder.”
That’s gorgeous writing!
But in tech writing, gorgeous isn’t the goal. Precision is. We don’t want readers to have any confusion about what we’re discussing.
For example, if we’re writing a study guide for a commercial driver’s license exam, we’d want to call a semi-truck a semi-truck. End of story. We wouldn’t want to also call it a tractor-trailer truck, a big rig, or an eighteen-wheeler.
In the same vein, if we were writing an IT user manual, we wouldn’t want to refer to “menu commands” in certain places, but “menu items” or “menu options” in others. We’d want to pick one term and stick with it.
Certain words can have multiple meanings — even function as different parts of speech. For example, you can “shed” your jacket; you can also store tools in the “shed” behind your house.
In technical writing — particularly in pieces that may be translated — you want to use words as only one part of speech. In that IT user manual, for example, you use “display” only as a verb, to refer to information a program is outputting. If you want to talk about the physical display that sits on a user’s desk, you’d use the word “monitor” instead.
Remember when we said that tech writing isn’t about poetry, it’s about precision? That means you need to cut idioms, metaphors, and slang from your writing.
These bits of linguistic flair don’t translate well. And even if you don’t translate your documents, you don’t get a free pass.
That’s because many readers of technical documentation don’t speak English as their first language. Including phrases like “playing hardball” or “batting a thousand” simply makes your content harder for those readers to understand.
Making sure that tables and figures are numbered sequentially may sound like a no-brainer. But when tech documents are put through review, it’s common for new sections be added, figures to be removed, and text to be converted into tables. The numbering of those figures and tables can quickly get skewed.
Unfortunately, this is an easy error for editors to miss. Many editors are trained to read through a document slowly and carefully, end to end, looking for mistakes. They don’t always read across pages — skipping from figure to figure to make sure that each one has been numbered correctly and sequentially, and that each has an appropriate callout in the text.
As tech writers and editors, we need to get this right. We don’t want to send our readers on a wild goose chase for “Figure 19,” when “Figure 19” doesn’t exist—or has been relabeled as “Figure 18b.”
One of the basic tenets of technical writing is to make the content easy for your reader to understand. Any roadblock to their understanding degrades their trust in your content — and will often make them stop reading altogether.
What, then, is a reader to make of instructions like this?
“The 12:00 position immediately after the date changes to the first is the 0-position of the function-hand. After correcting the Date Wheel to the “31st” by turning the crown, press button (A) to finely correct the Function Hand so that the function hand is aligned to the 0 position after the date wheel changes to the “1st”.
Not only are the instructions utterly confusing, the inconsistent capitalization, hyphenation, and spelling tell the reader one thing: this content was written by a hack, and you may as well not read it.
So how do we create content that readers trust? How do we write instructions that readers actually use?
The guidelines in this article give you a great place to start: dig deeply into your topic, respect your reader, break your content into digestible chunks, and label each one with an informational headline.
Next step? Use an automated tool like PerfectIt to help you manage the details.
PerfectIt acts like your own personal quality control specialist. It takes care of tedious editorial steps, so you can focus on the big picture.
When you run PerfectIt on a document, it will:
PerfectIt provides robust consistency checking right off the shelf. But tech writers and editors often pride themselves on being “power users” of software. Tech writers can get even more bang for their buck from PerfectIt by creating custom styles for their various projects.
For example, you can customize PerfectIt to:
In short, the ways that PerfectIt can help tech writers and editors maintain quality control are almost limitless. And when PerfectIt takes care of the details, you can focus on the big picture—creating documentation that’s comprehensive, useful, and easy-to-read.
Samantha Enslen runs Dragonfly Editorial, an agency that helps companies worldwide create clear, powerful content. Sam is vice president of ACES, The Society for Editing, and the former managing editor of ACES’ quarterly journal, Tracking Changes. At Dragonfly, she leads a team of writers, editors, and designers who often use PerfectIt to help them polish their copy.