Karlonia.com
For Gold, Peace, and Freedom

Karlonia.com

A Technical Writer’s Guide to Instruction Writing

October 14th, 2008

user-technical-manual.jpgThis article by Cheryl Frost discusses some basic tips and guidelines for writing instruction manuals. I can attest to the fact that this is a much-needed skill for many companies, especially with the increasing number of electronic gadgets and software applications being released to the retail markets. Over the years I have seen many poorly written instruction manuals that were included with PC and console games. Some contained obvious spelling or grammatical errors, while others were so vague and dumbed down that they failed to provide any useful level of detail about how to play the game or what the various statistics in the game really meant. If you are ever in a position where you need to write a technical manual of some sort, you can not only use the tips in this article, but you might also want to look at my post on the importance of English usage and proofreading before you actually have your manual published.


When people read instructions, they typically want the most important information fast. It is likely the reader is already in a bad mood, having been forced to read instructions after attempting a task without them. Simple, easy-to-follow instructions will help reduce further frustration.

Here are a few basic guidelines:

  1. Know your audience.
  2. Provide a brief introduction.
  3. Make each step a command.
  4. Use numbers for commands and bullets for options.
  5. Test and Revise

Know Your Audience

If you are writing a technical manual, you might assume the reader has a technical background. The reader may, in fact, be a trainee in a company with very little technical knowledge. For reasons like this, it is important to know who you are writing for so you don’t end up causing unnecessary frustration.

Provide a Brief Introduction

People need to know ahead of time, before they put time and effort into it, that the instructions they are about to read will help them with their task. A brief introduction tells the reader what to expect so they won’t waste time reading the wrong thing.

Write Each Step as a Command

  1. Tell the reader exactly what to do, using the imperative, active voice.

Good: Plug the cable into the wall.

  1. Never use the passive voice, which detaches the reader from the task and leaves them wondering if they should do something.

Bad: The cable should be plugged into the wall.




Use Numbers for Commands, Bullets for Options

If you want your reader to perform tasks in a certain order, be sure to number each step. This acts as a checklist so readers can keep track of where they are in the procedure. If you have steps that are optional or those without any particular order, use bullets to mark them.

Test and Revise

Don’t just assume that your instructions will work just because you understand them. Create a prototype of the product or environment and conduct a usability test to see if others can follow the instructions as well. If there are any flaws at all, revise them and test again.

Other Tips for Instruction Writing

To be successful in instruction writing, you need:

  1. Clear, simple writing
  2. A thorough understanding of the procedure
  3. The ability to put yourself in the position of the reader
  4. The ability to visualize the procedure in great detail
  5. The willingness to test and revise and revise again until the instructions are fit for their intended audience.

Graphic options

Graphics make a great supplement to written instructions. Often readers will follow procedures by the pictures alone. This is not always ideal, especially when the graphics don’t make any sense. Graphics should never replace written instructions and if used, should apply the same guidelines, including the testing process.

Consequences of Poorly Written Instructions

Bad instructions can:

  • Invoke frustration
  • Drive away consumers
  • Lead to unnecessary injuries.

With technical writing, particularly instruction writing, it is important to understand your audience. The purpose of instructions is to solve a problem; therefore, it is vital that you write your instructions without adding problems. Following the guidelines set out in this article will ensure successful writing results. Most importantly, the instructions you create will be safe, stress-free, and technically professional.



One Response to “A Technical Writer’s Guide to Instruction Writing”

  1. comment number 1 by: DragonWiz263

    Thank you for sharing this wonderful post. I find this information very useful and also it gives me a better understanding and perspective of Technical Writing/Instruction Writing.

Post Your Comments, Opinions, or Suggestions Here:

Name

Email (optional)

Website (optional)