We all make mistakes when we write, but when writing technical documentation, small mistakes can add up to a large consequence – and they could even harm the user or the person on the receiving end. Since it’s about that time to make New Year’s resolutions, it’s a good time to remember common mistakes made in technical writing – and then promise not to make them next year. Here are seven mistakes to be watch for and avoid in the new year.
Making things simple, isn’t that the goal of all writers? When technical writing is needed, it’s not for the technical writer to necessarily use, but it’s designed for some sort of end user. The case for simplicity becomes clearer when you think about it in this way, but is it possible?
Simplified design is one thing, but simple words are another. The good news is that the two can work hand in hand. By focusing on a few common attributes of the audience, technical writers can engage their audience, even when they never meet them in person.
The need for instruction – Users of technical documents need to be trained in the topic of the technical writing document. If they didn’t need the information, they wouldn’t be reading the document in the first place. Writers need to keep in mind that instruction is often the primary goal. With simple instructions, readers are better able to use the document to reach the greater goal(s).
When you purchase an item, it often will come with a warranty. And in that warranty, you will learn what measures you can take if the product should be defective or harmful during its intended use.
If you follow the terms of the warranty, you are often afforded the opportunity for a replacement product or some other compensation, should the product fail during the time you have owned it. Technical writers create these documents, often, and how they phrase a warranty will help to create more customer power.
Here are a few of the different parts of a warranty that need to be clearly defined:
Time period of the warranty
What is covered by the warranty
What is NOT covered by the warranty
Who the customer needs to contact to receive compensation
It makes sense that when you’re writing a technical document that you need to get the facts right. If the user can’t use the handbook or manual, that can spell trouble and it can be dangerous. But does the writing matter at all? Other blogs have already talked about this topic and it seems that the discussion is one without a clear answer.
Just the Facts, Ma’am?
What’s interesting about the quote, ‘Just the facts,’ is that Joe actually didn’t ever utter it as Friday on Dragnet. But it’s been repeated enough in popular culture that everyone assumes that he said it. He didn’t.
What does this have to do with technical writing? When you’re creating a document, you need to focus on the facts first, to be certain. But when your writing isn’t accurate, that can mangle the facts and cause a reader to interpret what you’re writing in a different way than you meant.
The story of going to get a fire hydrant to put out a fire, but then having difficulties knowing how to use it because of the instructions is a terrific illustration of technical writing gone wrong. Most of us think of writing as having to be deep or profound, but technical writing is another concept altogether.
The Problem of Solving Problems
Technical writing begins with a problem, essentially. This problem could be that a person needs to learn something or that they need to relearn something after a change. In either case, the audience needs to be able to use the information to reach a certain goal or set of goals.
When you think about technical writing, you probably think about the dry writing that fills software manuals or other user handbooks. Boring and dull – but is this the only way to approach technical writing? Not at all.
What you might not realize is that technical writing happens whenever someone instructs someone else. This might be something as basic as a recipe or something more complicated, like how to handle hazardous materials.
For many people, the concept of technical writing doesn’t seem to bring up arguments about language. After all, the precision needed in technical writing seems to indicate that there are fewer arguments about grammar and word usage than in other forms of writing. But is this the case? Within the area of technical writing, standards seem to be necessary, but they also seem overly rigid in some writing situations.
Clemson University students made a video for their technical writing class to show how electricity is delivered to the school. While this seems unorthodox, maybe there’s something to it. Maybe technical writing needs to be visual in more than just a 2D booklet or user guide.
Editor’s Note: This was the feature article in this month’s TechCom Manager newsletter, reprinted here with permission. Click the previous link to subscribe to the newsletter.
Buckley Jeppson
On October 13, 2010, President Obama signed into law the Plain Writing Act of 2010, a law that aims to make federal government writing clearer. This article summarizes the new law, briefly explains the nature of Plain Language writing, and outlines the implications for technical communicators.
Efforts to implement Plain Language into government writing started back in the Clinton Administration and were heavily evangelized by then-Vice President Al Gore, but this is the first time legislation has mandated a change in the way government communicates with the public.
In the NY Times blogs, a reader wrote about the idea of the oil spill as a case study in technical writing.
Fascinating to read, this blog brings up a number of ideas related to technical writing that deserve a closer look.
Ease of Understanding for the Target Audience
When writing a technical document, it’s essential the document be constructed in a manner that relates the information in an effective way. If the document is too complicated, readers will not be able to use it, unless they have the proper background. If a document is too simple, then the reader may miss details that can inform later decisions. Identifying the audience that will use the document will help to create a strong starting point from which to construct a technical writing document.
Impact on Users
Though the technical writing may not be as life changing as the oil spill, writing for an audience means that the audience will be impacted by the content. Keeping the impact of the content in mind allows the technical writer the opportunity to look at the information and relay those parts of the process that might have impact later, if they do not already. Better said, when a technical writer keeps in mind the outcome of the process they are describing, they will ensure all of the details are included that might affect the way the outcome looks.
Overall Presentation
The chart the class used in order to look into the oil spill as a case study is simple and clean. This allows a person to easily review the overall picture before looking at the more minute details. With this sort of presentation, a person doesn’t feel overwhelmed by too many details up front, and are far less likely to skip over important details presented later on.
Creating a clean document is especially essential when it’s also clear that the impact will be great if the instructions aren’t followed precisely or the information isn’t easy to understand.
