Training
7 min read
Here at Dozuki, we see a lot of technical documents. In all of this written work, we inevitably come across some mistakes. But hey, pobody’s nerfect. That said, when you see as many technical documents as we do, you start to notice trends. Trends in technical documents can be dangerous because they create systemic inefficiencies in your procedures and impact the overall quality of work.
To help you avoid these issues in your organization, we’ve compiled five common tech writing mistakes to avoid, based on our experiences helping companies create instructions.
Mistake 1
Omitting Articles
It’s a fairly common technical writing practice to drop articles. We drop articles under the assumption that it is more efficient. Simple reasoning would dictate that less words equals a shorter reading time. However, dropping articles hurts more than it helps—especially when writing for an audience that’s reading the material for the first time.
Take these operational instructions for a “Batmobile” toy for example. What should be said is, “Press the Turbo Charger panel to release the exhaust flame. As the back wheels rotate, the “Flame” will also rotate.” Instead, articles were amputated from the sentence, leaving a disfigured collection of nouns and verbs for the reader to sift through.
Articles like “the”, “a”, and “an” tell the reader’s brain that a noun is coming. When you drop articles, the reader feels like their brain is skipping a beat. Essentially, it’s because sentences without articles sound unnatural, and our brain has to do additional work to process what should have been there. We not robot, after all. Not only does this negate the efficiency gains that omitting articles intended to achieve, it also adds to the comprehension time by creating extra work for the reader.
Mistake 2
Overuse of Industry Jargon
Experts tend to speak a different language when it comes to industry terminology. Of course, each industry has its own vernacular that requires a certain level of competency. Unfortunately, many technical writers can take this too far and operate under the assumption that all readers have the same knowledge-level as an expert.
We once read an instruction manual for a blender that said “secure the liquid-spill prevention cap to the top of the container.” Liquid-spill prevention cap? Most people would just call this a lid.
Whenever possible, use common words with accurate descriptors when talking about objects or procedures that the layperson might not be familiar with. This is a good practice because it helps you be more precise when writing, and also widens the audience of your technical documents, opening them up for feedback and continuous improvement.
Mistake 3
Creating Dense Text
All too often, we take an ample amount of information, (usually housed in someone’s head), and restate it onto a document template. So long as the information is accurate and in the right order, we consider it a success. However, when information is packed into dense paragraphs or run-on sentences, the reader is likely to skim through the text and miss crucial information.
Take this example from our Tech Writing Handbook:
“Assemble small 90° adapter fitting to outlet port of filter base and orient so that free end of fitting will point toward backhoe and angled about 30° upward from horizontal.”
If you’re like most readers, you probably didn’t make it to the end of that sentence. While run-on sentences like this might make sense to the writer, readers rely on things like periods and commas to make distinctions between ideas.
For instance, dividing the previous instruction allows each piece of information to be clear and direct:
- Attach the small 90° adapter fitting to the port of the filter base.
- The free end of the fitting should point toward the backhoe.
- Angle the fitting about 30° upward of horizontal.
Breaking down steps into smaller, direct components gives readers the opportunity to process each instruction thoroughly, preventing errors in the process.
Mistake 4
Neglecting to Mention the “How”
Generally, technical writing will do a great job explaining what needs to be done. “Fasten metal piping.” “Detach belt from the motor.” “Sanitize workstation.” But what most instructions lack, is an explanation of how that action should be performed.
For example, a child who is given instructions to “take out the trash,” could easily misinterpret the request as an invitation to throw loose garbage outside. In this instance the action of the instruction was clear, but the technique was vague. If your child tossed the contents of the trash out of the bag and onto the street corner, who would be to blame? The trash has technically been “taken out,” according to the instructions.
A more thorough set of instructions would avoid this ambiguity by thoroughly describing the technique in addition to the desired outcome. For example, “take the trash bag out of the can and place it in the garbage bin outside,” would be a more apt description of the process. While it’s important to be concise, leaving out elements that clarify technique increases the likelihood of incorrect assumptions. Don’t assume that your technician knows what “sanitize the workstation” means the same way you wouldn’t assume that “take out the trash” is a sufficient instruction for a toddler.
Mistake 5
Edit, Edit, Edit
While this may seem like a catch-all, we can’t count the amount of times we’ve seen the word “engineering” misspelled by actual engineers. Taking documents like essays, emails, or academic papers through rounds of proofing is commonplace. Yet, some of us seem to think that technical documents are immune from such scrutiny. In fact, technical documents should be held to the highest standard when it comes to proofreading.
Take these two sentences for example:
“The ultimate guide for summertime fun: grilling kids and family”
Or
“The ultimate guide for summertime fun: grilling, kids, and family.”
That’s right. The only thing standing between you and cannibalism is a handful of commas.
All too often, small but important mistakes like this don’t catch our eye during a first or second draft. Like we said, pobody’s nerfect. That’s why it’s crucial to get multiple rounds of feedback on a document before it’s released.
Written by Dozuki
Founded in 2011, Dozuki has been the leader in connected worker solutions for over a decade. We’ve helped hundreds of companies plan, implement, and scale our frontline digital transformation solution.