The focus for this chapter is one of the most important of all uses of technical writing—instructions. As you know, instructions are those step-by-step explanations of how to do something: how to build, operate, repair, or maintain things.

Apr 12, 2017  How to Write an Effective Internal Training Manual. In the spirit of “Love Thy Employee as Thyself,” here’s how to write an effective training manual that will help your employees (calmly. Your assignment is to write a user manual for your implementation of FCS. Your manual must be detailed enough that a novice user with no background with FCS could pick up your manual, read it, and be productive using your implementation of FCS. Execute the software, as well as provide details on how to use the program. Jun 04, 2007 Here are some basic guidelines to ensure your user manual will survive actual use. Ensure that the user manual can lie flat on a work surface when opened. Consider the environment of use and if necessary provide a robust user manual. Consider whether the user needs to hold the user manual and work at the same time. Provide durable covers and pages.

Be sure to check out the examples.

Writing Instructions

One of the most common and one of the most important uses of technical writing is instructions—those step-by-step explanations of how to do things: assemble something, operate something, repair something, or do routine maintenance on something. But for something seemingly so easy and intuitive, instructions are some of the worst-written documents you can find. Like me, you've probably had many infuriating experiences with badly written instructions. What follows in this chapter may not be a fool-proof, goof-proof guide to writing instructions, but it will show you what professionals consider the best techniques.

Ultimately, good instruction writing requires:

• Clear, simple writing
• A thorough understanding of the procedure in all its technical detail
• Your ability to put yourself in the place of the reader, the person trying to use your instructions
• Your ability to visualize the procedure in great detail and to capture that awareness on paper
• Finally, your willingness to go that extra distance and test your instructions on the kind of person you wrote them for.

By now, you've probably studied headings, lists, and special notices—writing a set of instructions with these tools probably seems obvious. Just break the discussion out into numbered vertical lists and throw in some special notices at the obvious points and you're done! Well, not quite, but that's a great start. This chapter explores some of the features of instructions that can make them more complex. You can in turn use these considerations to plan your own instructions.

Some Preliminaries

At the beginning of a project to write instructions, it's important to determine the structure or characteristics of the particular procedure you are going to write about.

Audience and situation. Early in the process, define the audience and situation of your instructions. Remember that defining an audience means defining its level of familiarity with the topic as well as other such details. See the discussion of audiences and steps to use in defining audiences.

Most importantly, if you are in a writing course, you'll need to write a description of your audience and attach that to your instructions. This will enable your instructor to assess your instructions in terms of their rightness for the intended audience. And remember too that in a technical-writing course it is preferable to write for nonspecialist audiences—much more of a challenge to you as a writer.

Number of tasks. How many tasks are there in the procedure you are writing about? Let's use the term procedure to refer to the whole set of activities your instructions are intended to discuss. A task is a semi-independent group of actions within the procedure: for example, setting the clock on a microwave oven is one task in the big overall procedure of operating a microwave oven.

A simple procedure like changing the oil in a car contains only one task; there are no semi-independent groupings of activities. A more complex procedure like using a microwave oven contains plenty of such semi-independent tasks: setting the clock; setting the power level; using the timer; cleaning and maintaining the microwave, among others. (The instructions on using a camera are organized by tasks.)

Some instructions have only a single task, but have many steps within that single task. For example, imagine a set of instructions for assembling a kids' swing set. In my own experience, there were more than a 130 steps! That can be a bit daunting. A good approach is to group similar and related steps into phases, and start renumbering the steps at each new phase. A phase then is a group of similar steps within a single-task procedure. In the swing-set example, setting up the frame would be a phase; anchoring the thing in the ground would be another; assembling the box swing would be still another.

Best approach to the step-by-step discussion. Another consideration, which maybe you can't determine early on, is how to focus your instructions. For most instructions, you can focus on tasks, or you can focus on tools (or features of tools).

Use task orientation. Focus on the tasks your readers want to perform; use how to or –ing phrasing on headings.

In a task approach (also known as task orientation) to instructions on using a phone-answering service, you'd have these sections:

• recording your greeting
• playing back your messages
• saving your messages
• forwarding your messages
• deleting your messages, and so on

These are tasks—the typical things we'd want to do with the machine. For further discussion, see the chapter on task analysis.

On the other hand, in a tools approach to instructions on using a photocopier, there would be these unlikely sections:

• copy button
• cancel button
• enlarge/reduce button
• collate/staple button
• copy-size button, and so on

If you designed a set of instructions on this plan, you'd write steps for using each button or feature of the photocopier. Instructions using this tools approach are hard to make work. Sometimes, the name of the button doesn't quite match the task it is associated with; sometimes you have to use more than just the one button to accomplish the task. Still, there can be times when the tools/feature approach may be preferable.

Groupings of tasks. Listing tasks may not be all that you need to do. There may be so many tasks that you must group them so that readers can find individual ones more easily. For example, the following are common task groupings in instructions:

1. unpacking and setup tasks
2. installing and customizing tasks
3. basic operating tasks
4. routine maintenance tasks
5. troubleshooting tasks; and so on

Common Sections in Instructions

The following is a review of the sections you'll commonly find in instructions. Don't assume that each one of them must be in the actual instructions you write, nor that they have to be in the order presented here, nor that these are the only sections possible in a set of instructions.

As you read the following on common sections in instructions, check out the example instructions.

Schematic view of instructions. Remember that this is a typical or common model for the contents and organization—many others are possible.

Introduction. Plan the introduction to your instructions carefully. Make sure it does any of the following things (but not necessarily in this order) that apply to your particular instructions:

• Indicate the specific tasks or procedure to be explained as well as the scope of coverage (what won't be covered).
• Indicate what the audience needs in terms of knowledge and background to understand the instructions.
• Give a general idea of the procedure and what it accomplishes.
• Indicate the conditions when these instructions should (or should not) be used.
• Give an overview of the contents of the instructions.

See the section on introductions for further discussion.

General warning, caution, danger notices. Instructions often must alert readers to the possibility of ruining their equipment, screwing up the procedure, and hurting themselves. Also, instructions must often emphasize key points or exceptions. For these situations, you use special notices—note, warning, caution, and danger notices. Notice how these special notices are used in the example instructions listed above.

Technical background or theory. At the beginning of certain kinds of instructions (after the introduction, of course), you may need a discussion of background related to the procedure. For certain instructions, this background is critical—otherwise, the steps in the procedure make no sense. For example, you may have had some experience with those software applets in which you define your own colors by nudging red, green, and blue slider bars around. To really understand what you're doing, you need to have some background on color. Similarly, you can imagine that, for certain instructions using cameras, some theory might be needed as well.

Equipment and supplies. Notice that most instructions include a list of the things you need to gather before you start the procedure. This includes equipment, the tools you use in the procedure (such as mixing bowls, spoons, bread pans, hammers, drills, and saws) and supplies, the things that are consumed in the procedure (such as wood, paint, oil, flour, and nails). In instructions, these typically are listed either in a simple vertical list or in a two-column list. Use the two-column list if you need to add some specifications to some or all of the items—for example, brand names, sizes, amounts, types, model numbers, and so on.

Discussion of the steps. When you get to the actual writing of the steps, there are several things to keep in mind: (1) the structure and format of those steps, (2) supplementary information that might be needed, and (3) the point of view and general writing style.

How To Write An Introduction For A Manual

Structure and format. Normally, we imagine a set of instructions as being formatted as vertical numbered lists. And most are in fact. Normally, you format your actual step-by-step instructions this way. There are some variations, however, as well as some other considerations:

• Fixed-order steps are steps that must be performed in the order presented. For example, if you are changing the oil in a car, draining the oil is a step that must come before putting the new oil. These are numbered lists (usually, vertical numbered lists).
• Variable-order steps are steps that can be performed in practically any order. Good examples are those troubleshooting guides that tell you to check this, check that where you are trying to fix something. You can do these kinds of steps in practically any order. With this type, the bulleted list is the appropriate format.
• Alternate steps are those in which two or more ways to accomplish the same thing are presented. Alternate steps are also used when various conditions might exist. Use bulleted lists with this type, with OR inserted between the alternatives, or the lead-in indicating that alternatives are about to be presented.
• Nested steps. In some cases, individual steps within a procedure can be rather complex in their own right and need to be broken down into substeps. In this case, you indent further and sequence the substeps as a, b, c, and so on.
• 'Stepless' instructions. And finally there exist instructions that really cannot use numbered vertical list and that do little if any straightforward instructional-style directing of the reader. Some situations must be so generalized or so variable that steps cannot be stated.

See the chapter on lists for the style and format of these possibilities.

Supplementary discussion. Often, it is not enough simply to tell readers to do this or to do that. They need additional explanatory information such as how the thing should look before and after the step; why they should care about doing this step; what mechanical principle is behind what they are doing; even more micro-level explanation of the step—discussion of the specific actions that make up the step.

The problem with supplementary discussion, however, is that it can hide the actual step. You want the actual step—the specific actions the reader is to take—to stand out. You don't want it all buried in a heap of words. There are at least two techniques to avoid this problem: you can split the instruction from the supplement into separate paragraphs; or you can bold the instruction.

Bolding actual user steps in instructions. Bold text helps distinguish the actual action from the supplementary information.

Avoid telegraphic writing—omitting 'understood' articles (the, a, an). True, robots write that way, but we don't have to.)

Writing style. The way you actually write instructions, sentence by sentence, may seem contradictory to what previous writing classes have taught you. However, notice how 'real-world' instructions are written—they use a lot of imperative (command, or direct-address) kinds of writing; they use a lot of 'you.' That's entirely appropriate. You want to get in your reader's face, get her or his full attention. For that reason, instruction-style sentences sound like these: 'Now, press the Pause button on the front panel to stop the display temporarily' and 'You should be careful not to ...'

A particular problem involves use of the passive voice in instructions. For some weird reason, some instructions sound like this: 'The Pause button should be depressed in order to stop the display temporarily.' Not only are we worried about the Pause button's mental health, but we wonder who's supposed to depress the thing (are you talkin' to me?). Or consider this example: 'The Timer button is then set to 3:00.' Again, as the person following these instructions, you might miss this; you might think it is simply a reference to some existing state, or you might wonder, 'Are they talking to me?' Almost as bad is using the third person: 'The user should then press the Pause button.' Again, it's the old double-take: you look around the room and wonder, 'Who me?' (For more detail, see passive-voice problem.)

Another of the typical problems with writing style in instructions is that people seem to want to leave out articles: 'Press Pause button on front panel to stop display of information temporarily' or 'Earthperson, please provide address of nearest pizza restaurant.' Why do we do this? Do we all secretly want to be robots? Anyway, be sure to include all articles (a, an, the) and other such words that we'd normally use in instructions.

Graphics in Instructions

Probably more so than in any other form of writing (except maybe for comic books), graphics are crucial to instructions. Sometimes, words simply cannot explain the step. Illustrations are often critical to readers' ability to visualize what they are supposed to do.

In a technical writing course, instructions may require you to include illustrations or other kinds of graphics—whatever would normally be used in the instructions. The problem of course may be that you don't have access to graphics that would be suitable for your particular instructions, and that you don't feel wildly confident in your artistic abilities. There are ways to overcome these problems! Take a look at the suggestions in graphics. In that chapter, you'll see not only suggestions for creating graphics, but also requirements on their format.

Format in Instructions

Headings. In your instructions, make good use of headings. Normally, you'd want headings for any background section you might have, the equipment and supplies section, a general heading for the actual instructions section, and subheadings for the individual tasks or phases within that section. Take a look at the examples at the beginning of this chapter. See headings for common requirements.

Lists. Similarly, instructions typically make heavy use of lists, particularly numbered vertical lists for the actual step-by-step explanations. Simple vertical lists or two-column lists are usually good for the equipment and supplies section. In-sentence lists are good whenever you give an overview of things to come. See lists for common requirements.

Special notices. In instructions, you must alert readers to possibilities in which they may damage their equipment, waste supplies, cause the entire procedure to fail, injure themselves or others—even seriously or fatally. Companies have been sued for lack of these special notices, for poorly written special notices, or for special notices that were out of place. See special notices for a complete discussion of the proper use of these special notices as well as their format and placement within instructions.

Indentation of notices in instructions. In the first example, notice how the notice is indented to the text of the preceding step. In the second example, notice that the severe notice is placed at the beginning before any of the steps.

Number, abbreviations, and symbols. Instructions also use plenty of numbers, abbreviations, and symbols. For guidelines on these areas.

Revision Checklist for Instructions

As you reread and revise your instructions, watch out for problems such as the following:

• Make sure you provide real instructions—explanations of how to build, operate, or repair something.
• Write a good introduction—in it, indicate the exact procedure to be explained, indicate audience requirements, and provide an overview of contents.
• Make sure that you use the various types of lists wherever appropriate. In particular, use numbered vertical lists for sequential steps.
• Use headings to mark off all the main sections and subheadings for subsections. (Remember that no heading 'Introduction' is needed between the title and the first paragraph. Remember not to use first-level headings in this assignment; start with the second level.)
• Use special notices as appropriate.
• Make sure you use the style and format for all headings, lists, special notices, and graphics as presented in these chapters. If that's a problem, get in touch with your instructor.
• Use graphics to illustrate any key actions or objects.
• Provide additional supplementary explanation of the steps as necessary.
• Remember to create a section listing equipment and supplies, if necessary.

I would appreciate your thoughts, reactions, criticism regarding this chapter: your response—David McMurrey.

Contents

Know who you are writing for

If you know who your target group is, you know two very important things that are necessary to write a high-quality user manual.

First, you know something about the tone of voice. If you are writing a user manual for first-time users of an alarm system, it could be that you need to explain how to set up the sensors in a room. You should motivate them to have a look at several examples so that users can use the sensors effectively. This requires setting up some kind of motivational relationship with the reader so that he/she gets the most out of your product.

However, if your product does not need an introduction because users will be familiar with it right from the start, you could leave out examples or any advice to experiment. Your language could be more business-like, just pointing out where the relevant buttons are.

The second consideration aligns pretty well with the first point made. Any target group values its own level of detail. It is not necessary to explain to maintenance personnel how to clean a manufacturing machine. People from this group would be offended if you would spell out what to do. However, it is necessary to tell personnel from a small company how to replace printer cartridges. Or to inform them when a printer would need internal cleaning.

It is always important to keep in mind who you are writing for.

A good start is your Table of Contents

Why is a Table of Contents a good start? Because a Table of Contents forces the writer of a user manual to think about what he/she wants to say in what order. Of course, there will be a foreword or an introduction in any user manual. Without doubt, there will be safety instructions at the beginning of the manual as well. There will also be some maintenance issues at the end. But what should you put in between those chapters?

This all depends on the product itself. For some products the settings are important: one day a pump may work ‘normally’, another day it may be best to set it in reverse. This could depend on water levels, for example. A chapter called “Everyday settings” could be appropriate here. Another chapter may be about collecting information how much water has been transported and to where exactly. One could call such a chapter “Monitoring results”.

Take another example: a so-called ‘multifunctional device’. For a ‘multifunctional’ the chapters in a Table of Contents could be based on, indeed, its different functions: printing, copying, scanning, faxing, and so on.

As long as there is some logical order that the user can relate to, the user manual lends itself for effective scanning. In this respect, it is absolutely essential that each chapter and each paragraph has a clear-cut title: “Printing using your computer”, “Copying without your computer”, “Scanning to your computer” and so on.

Collect all necessary information

How To Write A Product Manual

A technical writer has the reputation of being inward looking, interested as he/she is in only one thing: technology.

This reputation does not do him or her justice. A technical writer should know a lot about voltage, current, resistance and megahertz. But he should also know how to collect all the necessary information. Quite a lot information may be available on paper or digitally. One could think of a risk analysis, 3D CAD illustrations, data sheets and so on.

But it is quite possible, even probable, that this information does not answer all the questions a technical writer has in mind. After all, a technical writer wants to place himself in the shoes of the user. If the documentation does not elaborate on the need for a pump to be set in reverse, he needs to ask the experts: why is it necessary to set this specific pump in reverse?

This means a technical writer has to have communication skills. He also has to have social skills. Placing yourself in the shoes of another person has everything to do with wanting to know the other person.

Portraying a technical writer as a ‘technician only’ would be a mistake. It takes more to write a user manual than being ‘tech savvy’.

Actually writing (illustrating?) your user manual

OK, you have collected all necessary information. Now it is time to actually write your user manual. Three considerations spring to mind.

The first consideration has to do with minimalism. Minimalism is a philosophy not to spend more words on a subject or task than is strictly necessary. It is not necessary to tell the reader that a valve is available in three colors when the only valve on a tank is red. A user only needs to know how to use the valve and when. This may sound very obvious, but proves to be quite a challenge in (too) many cases. Some companies do not throw away their ‘marketing head’ easily.

The second consideration is: always use Simplified Technical English if you want to be business-like. Simplified Technical English, or STE for short, does away with words that are ambiguous, such as ‘to carry out’. ‘To carry out’ could mean ‘taking something away from a certain location’, but also ‘taking action’. In STE, only the verb ‘to do’ will do. Also, STE limits the number of words in a sentence to roughly 20. This make any sentence easy to understand.

The third consideration is also very important. Why use text if an illustration works just as well or even better? After all, an illustration takes away the need to translate text. But even more important is the fact that people are first and foremost visually oriented. The saying ‘A picture tells you more than a 1,000 words’ implies that people grasp the meaning of something faster and better when it is illustrated. You cannot present all information visually (“Be sure the holes are free of wood chips and saw dust”). But where you can, the benefits for the user can be enormous. Thus, ‘writing a user manual’ takes on a whole new meaning.

Choosing the appropriate format

There still is one choice left: what kind of layout do you want? Or, in jargon: what is the template you want to define so that your user manual not only matches the wishes of the user, but also your corportate identity? Consistency is key here: every chapter and every paragraph should look the same.

There are software tools available that help you to define a professional template. What’s more: there are content management systems on the market that can transform a single source text into any format required, whether this format would be an A5 booklet, an A4 book, a PDF file (portrait or landscape) or a website that adjusts itself automatically when presented on a computer or tablet or smartphone.

Companies that are specialized in writing user manuals know how to help you choosing the relevant formats – in case you would need advice.