Determining Appropriate Level of Technical Writing

The challenge in delivering usable information is in knowing what level of detail and complexity is appropriate, and what elements of a given process you can assume that your reader knows and which ones you'll have to explain. Even if a teenager who is learning to drive has never started a car before, they will most likely know where to put the key and how to turn on the ignition from years of sitting in the front seat as a passenger and observing. If you were writing a set of instructions for them on how to drive, you could simply say "start car" and move on to the next step without explanation. You wouldn't have to explain what a car is and what it can do. Your reader knows these things in this case, so to explain to them would be a waste of your time and theirs.

Hypothetically, though, what if you needed to teach the same skill to someone with no observational experience? What if an alien landed on earth and instead of saying "Take me to your leader." it said "Teach me to operate your vehicle." This may sound pretty simple, but it's a way to remember to think about what your user may already know and what you'll have to explain. Let's illustrate technical writing in action by teaching an alien to drive.

Break Down the Steps

As we discussed above, you could just tell your teenager to start the car, but our alien will need more detail. Let's assume that this hypothetical visitor to our planet understands and reads English and has hands and feet that resemble ours. On his world, though, all the vehicles operate through mind control, so steering wheels and pedals are strange to him. What steps will be needed to help him learn to start the car?

It may be helpful to briefly explain how a car engine works.

This car contains an internal combustion engine, meaning that small explosions inside it cause pistons to move up and down, causing the drive train to spin.
The engine is started by means of an ignition system that sends an electric spark to the engine and ignites the fuel.

Okay, there are a lot of terms here our alien might not understand. To keep from actually writing the world's longest owner's manual here, we'll pretend that we've defined these terms.

The ignition system is ignited by turning a key in the appropriate slot. The key is a security measure designed to insure that only authorized individuals operate the vehicle.
The steering wheel is the circular object sticking out on the vehicle's driver's side (we would definitely want to include a drawing or photo here). The ignition key slot is located on the right side of the steering column below the steering wheel (time for another drawing).

There are yet more terms here that may need definition depending on the user. As you write your technical copy, ask yourself if your users are likely to understand terms and concepts. If not, how can you explain to them so that users learn what they need to know without getting bogged down? For the sake of brevity, again, we are going to leave some terms undefined in this example.

Place the key in your right 'hand.' Insert the key in the slot. Rotate the key clockwise until you feel resistance, about one quarter turn. We would probably have to define clockwise for an alien, wouldn't we?
When you turn the key, you should hear the engine starting and see your dashboard lights going on. As soon as the engine has started, relax the pressure on the ignition key and allow it to return to its original position.
NOTE: It is important to relax pressure on the key as soon as the engine starts. Continuing to run the ignition system can flood the ignition chamber with fuel and stall the engine.

With this set of instructions, we've hopefully succeeded in helping our alien friend start the car. Again, most of these steps would be assumed when teaching a human driver who has had an opportunity to observe cars starting in the past. By considering the needs of our audience, we have strived to provide all of the detail necessary to help the user succeed.

Interested in learning more? Why not take an online Technical Writing course?

What if there is something wrong with the car and it doesn't start? Most manuals will include a troubleshooting section. We might include a reference beneath these instructions to let the user know what to do if something goes wrong.

If the engine does not start when you turn the key, refer to Chapter X, "Troubleshooting."
WARNING: Turning the key in the ignition for more than five seconds can flood the system and prevent it from functioning. Do not turn the key for too long. See Chapter X, "Troubleshooting," or call our toll free number for assistance.

Glossaries and Appendices

As we've said, we need to make sure that the terms we're using are understandable, but we don't want to bog our copy down with so much information that the user can't get started. One way to get the best of both worlds is to make your instructions fairly lean while providing more information for those who need it by including optional reference sections in your user help manuals.

Glossaries.
Glossaries are like brief dictionaries, defining a set of terms used within a text for those who don't understand them. Including bold text or some other way of highlighting terms available in the glossary can be useful for the reader.

Terms highlighted in bold are explained in the glossary (see page XX).
The ignition system is ignited by turning a key in the appropriate slot. The key is a security measure designed to insure that only authorized individuals operate the vehicle.
The ignition key slot is located on the right side of the steering column below the steering wheel.

When the reader turns to page XX, you will find a glossary explaining terms in greater detail, possibly with an illustration as well.

Steering Wheel. A circular object located on the driver's side (left side) of the vehicle. The driver can control the vehicle's direction by turning the steering wheel in the direction they wish to travel. (Include a photo or drawing.)

Appendices. For topics that take more than a glossary entry to explain, you may wish to include an appendix. Appendices are supplementary chapters toward the end of the manual that provide more detailed information for those who need it. Appendices can help keep your instructions concise enough for advanced users while including enough detail to help beginners get up to speed.

Insert key in ignition slot and turn (For more information on ignition systems and how they work, see Appendix 1.)

If your product lends itself to online help files, you can link directly to glossaries and appendices by means of a hyperlink, either by prompting readers to "click here for more information" after a term is introduced, or by linking directly to the word.

Insert key in ignition slot and turn.
Insert key in ignition slot.

Sell the Benefits

Reading a manual and learning something new can be challenging and stressful for your users. While you're teaching them to use the product, you might want to remind them that all this work reading the manual is worth their time and effort. Spend a little time selling the benefits of knowing how to use the product and reminding them what they have to gain.

If you've successfully started the car, congratulations! You're almost ready to travel. Soon you'll be able to take yourself and all your extraterrestrial buddies anywhere you want to go. But first, we've got just a little more to learn. Next up, shifting into gear!

Get Feedback

We've said it before, but it bears repeating. A great way to see if you've got the right amount of detail is to try to put yourself in your reader's shoes (assuming aliens wear shoes). When you've done the best you can by evaluating your own work, try it out on some trial users. Try getting feedback from less technically oriented employees at your company, or assemble a team of beta testers to try using your manual and operate your product. You will want to know that you've done everything you can to provide help that is truly helpful.