10 Bad Technical Writing Examples
Who said that you can’t have fun with technical writing?
Some may be under the pretense that technical writers are strait-laced, perfectionists, but we all make mistakes. As with most of us in the early stages of our careers, making a faux pas is part of the journey. That being said, it’s probably best if we learn how to avoid the most common mistakes made right out of the gate.
Have you ever read through a bad instruction manual and wondered if the company possibly included the wrong slip of paper? The instructions seem to be detailing piece parts that don’t exist within the product that’s sitting right in front of you. Or maybe you’ve glimpsed a diagram to a convoluted handbook that makes you wonder if it got mixed in from one of your kids’ games?
These are telltale signs of a technical document gone awry. Below is a list of the top ten bad technical writing examples and how to fix each common mistake in technical documentation.
1. Indecipherable titles
These are the introductory titles that thwart readers from even opening up to the first page. They are so pretentious that they are intimidating and therefore, too scary to flip to the first page.
Here's an example of a title to avoid: The All-inclusive and Thoroughly Vetted Interdepartmental and Multi-functional Manual Pertaining to Optimal Performance of The Richards 77 of the Modular 3.3abx Series.
Learn technical writing and get instructor feedback and coaching on your actual technical document.
Learn More & Download an OutlineDocuments like these get scrunched and pushed back to the very back of the drawer and never, ever pulled out to the light of day for reading. Your goal in technical writing is to have it read from cover to cover and fully understood in one focused reading so as never to be needed again. Or to be so helpful that it is used as a technical bible, taken out to be consulted time and again for its easy-to-digest, pertinent information.
The solution: Do just that. Keep your title concise and in plain, simple language. In this case, “The Richards-37 User Manual” would suffice.
2. Glaringly incorrect, absent, or poor-quality images
It is wholly frustrating and bewildering to consult a shoddy one-page how-to document that leaves out key images or elements. For example, an entire set of figure numbers 8-11 are missing. Or the image for 2.9 is fuzzy or appears to have been photocopied from a third-generation diagram.
The solution: Display modern and matching photos and images. Know that technical writing is a collaborative effort. There should be other parties performing a QA and assisting with the design content.
Not all technical documents are prepared with the aid of cutting-edge tools and techniques (although in this Digital Age, it is preferred). At the very least, make sure that your visuals are clear and in alignment with the words these have been chosen to represent.
3. Confusing substance
A large blunder in the world of documentation is the delivery of a hard-to-understand output. Content that is ambiguous stands in direct contrast to the whole purpose of technical writing. With an audience of laypeople, you need to use layman’s terms. Being hazy in vocabulary, word order, or description is a no-no.
The solution: This is an easy fix. Consider your audience's needs and make sure that your writing is direct, accurate, clear, and simple. If unsure of a sentence or instruction, run it by a non-expert. A successful technical document is judged by how well it is understood by the readership, not by the technical terms you use.
4. Circular cross-reference
This is when you reference a point of instruction, only to find that it references the first, resulting in a closed loop. Think of this as a treasure hunt where the treasure is never to be found. Reading through a manual is enough of a challenge. It’s never fun to have to dig around for the instructions.
The solution: Another easy fix. You must have an individual or many who proof your work. They need to read and re-read your document assuming the perspective of a non-expert. All errors and miswrites should be avoided with this tactic.
5. No TOC or Index
Not taking the time to craft a table of contents (which is super easy to compile) or an index is a sacrilege. For any non-fiction document, the inclusion of one of these is mandatory.
The solution: Include one or the other! There are plenty of online resources to help distinguish which one is best for your writing piece.
6. Jargon overload
This may be the most common offense. Technical writers sometimes forget that their audience is not “in the know.” They take for granted industry words and acronyms that the average reader may view as foreign.
The solution: Just be cognizant of the terms that you use. Acronyms are typically a “heads up” flag that calls for defining. Get some assistance by putting your text through a Jargon Grader. Always keep your audience in mind. If there aren't any proprietary issues, invite a friend to serve as your non-expert and read through your document.
7. Poor punctuation
For obvious reasons, bad grammar, spelling mistakes, typos, and missing or incorrect punctuation should be avoided. These mistakes can hurt reader comprehension. It also doesn't look professional.
The solution: In this Age of Information, there are plenty of incredibly useful grammar-check tools. Be sure to take advantage of what’s out there during the editing stage of your writing process. Vetted resources include Grammarly and Hemingway.
8. Inconsistency in tone
This is more commonplace than you might think, especially with medium- to large-sized documents. The compilation of a technical document is, more often than not, a team effort. The output may be the product of a collection of writing pieces from different contributors. Be mindful that inconsistency in tone can distract the reader.
The solution: It is wise for the primary author to make sure that they set the tone for the entire piece. They will need to re-write portions of the text according to a single, established dominant tone that is made evident throughout.
9. Overly focused on the formal
Readers are most comfortable with a professional yet grounded tone. Overly formal to the point of sounding pompous is not.
The solution: A good technical writer knows their audience. Always be aware of how your readership will interpret your writing. Be sure to write at the level of your readers. This is a fantastic readability tool to help with the effort.
10. Unclear antecedents
This is an error in writing when a sentence does not identify to which noun a subsequent pronoun refers. It is burdensome in technical writing when the reader must comprehend every point.
The solution: Just being aware of this issue in your writing style should resolve it. This site on antecedents offers clarity.
Last bit of advice for avoiding bad technical writing examples
Keep this list of bad examples at your desk, and read it before you set out to write technical documentation. It will keep you on the right track during the writing process. Then, upon completion of your assignment, read through it again.
If you really want to make sure it sticks in your technical communication, enroll in a specialized top-tier technical writing course to become a stronger tech writer. You'll improve your technical writing skills for any technical writing project.
Get instructor feedback and coaching on your actual technical writing in our online courses.
Enroll in a self-paced course and improve your technical writing today.
Download an Outline
