Ten Best Practices for Technical Writing and Editing
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.
Consider Your Reader
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.
If you’re writing for health care providers, you might talk about how effective your system is for “glycemic control in adult patients with Type 1 and Type 2 diabetes previously treated with continuous subcutaneous insulin infusions.”
If you’re writing for parents, you might say that your system is “easy to use and helps you and your older kids deliver and monitor insulin wirelessly.”
If you’re writing for young patients, you might say that your system lets them “jump on the jungle gym, with no wires in the way.”
Let your reader dictate everything from the terminology you use, to the sentence structures you choose.
Break Content into Standalone “Chunks”
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.
Label Each “Chunk” With a Meaningful Heading
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:
Choose a site for your garden
Determine the size of your garden
Build a wooden frame
Figure out how much soil you need
These headlines aren’t poetic, but they’re crystal clear.
Use Terms Consistently
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.
Watch Out for Multiple Meanings
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.
Avoid Idioms, Metaphors, and Slang
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.
Make Sure Tables and Figures Are Numbered Sequentially
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.”
Check that Hyphenation, Capitalization, and Spelling Are Correct and Consistent
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.
Automate So You Can Focus
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:
Check inconsistent capitalization. PerfectIt will let you know if you’ve used “Function Hand” in one place and “function hand” in another, and let you choose which treatment is correct. Bonus: when PerfectIt checks capitalization, it’s smart enough to recognize headings as headings, and help you capitalize those consistently as well.
Check inconsistent hyphenation. PerfectIt will also scan your entire document and let you know if you’ve hyphenated words inconsistently. Did you type “tractor-trailer truck” at one spot, and “tractor trailer truck” in another? PerfectIt will flag inconsistencies like that—even if they’re hundreds of pages apart.
Check inconsistent spelling. There’s a hashtag on Twitter called #spellcheckwontsaveyou for a reason. It’s because standard spellcheckers only flag words that don’t appear in the dictionary. PerfectIt does more: it lets you know if you’ve used alternate spellings for the same word. It will warn you, for example, if your HR manual refers to your “center of operations” in some places and “centre of operations” in others.
Check figure and table numbering. Lots of user manuals are chockful of figures. That means they’re chockful of opportunities for errors in figure numbering. Luckily, PerfectIt checks the numbering of tables, boxes, and figures to ensure that they appear in the correct order. It will warn you if some figures are labelled and others are not.
Customize PerfectIt for Even More Power
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:
Help you use terms consistently. Remember that manual for semi-truck drivers? You could set PerfectIt to flag any instances of alternate expressions for “semi-truck.” For example, PerfectIt could flag whenever “tractor-trailer truck,” “semi,” “big rig,” or “eighteen-wheeler” appeared in the document—and suggest that you use “semi-truck” instead.
Flag words with multiple meanings. If you were writing the IT user manual we mentioned earlier, you could set PerfectIt to flag “display” whenever it occurred, warn you to use it only as a noun, and suggest that you use “monitor” if you need a verb.
Avoid idioms and slang. If you’re writing material with a global audience, you could also customize PerfectIt to flag business-related slang and jargon and suggest more universally understood terms. For example, you could have PerfectIt flag “out of pocket” and suggest “unavailable” instead. Or flag “ideate” and suggest “think” or “plan.”
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.