Instructions

From TechWriter Wiki

Jump to: navigation, search

Contents

Introduction

Within Technical Writing, instructional texts may be referred to as User Procedures, Operating Procedures, Work Instructions, Tasks, Business Process Procedures (BPPs), and possibly other terms. Regardless of the term used, the approach to writing them is consistent. The language used should be purely functional, commanding, and direct.

Instructions are one of the most common forms of technical documentation, and almost all Technical Communicators will find themselves writing instructions at some point in their career. Because of this, it is perhaps worth taking a closer look specifically at the topic of writing instructions. This is doubly so when one sees the quality of 'user instructions' written by untrained staff, who seem to feel that it is just a matter of "writing down what you do".

Purpose

The purpose of instructions is to explain to a user how to carry out a specific, identified task. This is an extremely important point to bear in mind - epecially with regard to the difference between user instructions and user guides. Again, it is worth emphasizing: instructions explain how to do something and not what can be done.

When writing instructions, always start with the specification of the task. If you can't succinctly define the task, then you will not be able to provide effective instructions. Ask yourself: What is this task explaining? If you can phrase this as a single sentence, starting with "How to..." then you are on the right track. For example, your task specification could be "How to re-spool a strimmer", or "How to check a customer's credit".

Once you have the title, you can constantly validate your document against this, by asking: Is what I am saying contributing to the outcome of this task? Do they need this information in order to complete this task? If the answer is no, then the chance is that the information does not belong in the instructions (it may be perfectly valid or useful information, but not here). In addition, for each action that you describe in the document, ask yourself: Why does the user need to do this? or: Why would they want to do that? Again, if the answer is not obviously directly supporting the task specification, then you either need to omit this information, or need to provide a more explicit explanation of why they would need to carry out this action and how this contributes to the successful completion of the task.

Style

Instructions should instruct

One would have thought that the statement "Instructions should instruct" would be such a truism that it does not need to be stated. However, it is amazing just how often this simple rule is overlooked, even by experienced Technical Communicators. So often is it overlooked, in fact, that it bears repeating: "Instructions should instruct".

The first point at which you can check that you are adhering to this simple rule, is in the title of the instruction (and of course every well-formed set of instructions will have a title). If your title is "The printer cartridge" then the chances are that you are approaching the instructions from the wrong perspective. If, by contrast, your title is "Changing the printer cartridge" then this is a good sign that you are on the right path. Note, however, that instruction titles starting "How to..." should be avoided; if every instruction starts with the same two words, then these two words are effectively redundant. (See also comments on use of the gerund.)

Beyond the title, every element within the body of the instruction should actively support the user in carrying out the task being described (see also "Instructions should be task-based"). For example, when describing how to complete a field in a software application, it is unnecessary to mention the system table against which this field is validated. Knowing this will not help the user complete the task. (Unless, of course, the user themselves is responsible for maintaining the validation table; in which case the information should be presented as "If you cannot select the required value then you should first enter it into system table XYZ".)

Another common mistake made by 'system' people is to include elements of the design in the instructions, for example specifying the compression algorithm used when 'zipping' files. This should be resisted as far as possible. In most cases, users of a product (and especially users of domestic products, who may not have a technical or scientific background), do not need to know why a product works the way it does, or what is going on 'behind the scenes', they just need to know how to get the product to do what they want it to do. Of course, there are exceptions to this (such as where the user instructions will also include some degree of troubleshooting), but in general, it is safe to say that user instructions and design information should be kept separate.

Instructions should be clear, complete, and unambiguous

A set of instructions should allow a reader to start, execute and finish the activity being described, without recourse to look elsewhere for additional guidance. They should therefore contain all of the information that the user needs. Where this is not practical (for example, in a summary list of activities) the instructions should tell the reader where to find any information that is required but is not included in the instructions themselves.

Example

Avoid Use Instead
If required, make a full backup of your hard drive. Make a full backup of your hard drive. (See "Backing up your computer" on page 20 for details of how to do this.)

When carrying out a set of instructions, the reader should always be able to track the point they are at in carrying out the instructions, and identify what they have to do next. Fortunately, the easiest way of doing this is also the most commonly-used: numbered steps. Wherever possible, provide user instructions in the form of numbered steps. They are easy to follow, allow the users to appreciably monitor their progress, and most tasks naturally consist of a number of sequential activities anyway (readers understand instinctively that numbered steps are to be carried out in the sequence given - in contrast to bulleted-lists).

Well-written instructions leave the user in absolutely no doubt as to what they need to do.

There is a play-off between providing supporting information (to explain why a step is necessary, etc.) and keeping the instructions short/simple (i.e. not complicating/cluttering the instructions).

Instructions should be task-based

A set of instructions should always describe how to carry out a clearly-defined task. That is, there must be some predefined goal that is being accomplished (or result that is expected). Furthermore, this goal must be clear to the reader, and the reader must be able to identify when the task is complete. In other words, when they reach the end of the instructions, the reader must be able to see (or check) that the expected outcome has actually happened.

The tricky part is deciding exactly what constitutes a task. A useful guideline (though please bear in mind that it is nothing more than that - a guideline) is that a task is "a single unit of work, carried out at one time, from beginning to end". Thus, "Changing a printer cartridge" is a task, but "Building a house" is not. Of course, building a house is a bona fide task, just not where instructional documentation is concerned. When writing instructions for tasks as large as this (building a house), it is useful to bear in mind the old chestnut: "How do you eat an elephant?". The answer is, of course, "One bite at a time". It is the same with user instructions: if you need to instruct the reader on how to carry out a large or lengthy task, break the task down into manageable sizes (based on the guideline proffered above) and then write instructions for each of these.

This introduces the important concept of chunking (see also Information Mapping). For instructions that involve a large number of individual activities (or steps), it is worth considering breaking the instructions up into a number of smaller sets of instructions. The main reason for doing this, is that it makes the whole instruction set (for the single task being described) less daunting to the reader: readers will respond more favorably to 5 sets of 10-step instructions than they will a single set of instructions numbered 1 to 50.

However, as mentioned under "Instructions should be clear, complete and unambiguous" above, it is important that tasks are split at a logical point. This is normally at a point at which the user can see a specific result, or requires a different tool, or (for software) at the point that a new screen is displayed.

At this point, it is worth mentioning the oft-quoted 7 +/- 2 rule. Should you not be familiar with this 'rule', it was first developed by cognitive psychologists, who worked out that the human brain could hold approximately seven (plus-or-minus two) items of information in short-term memory at a time. Once this limit is reached, any new piece of information received, will displace an existing piece of information. This much has been proven to be true. However, it simply does not apply to documentation (despite its many advocates, including Robert E Horn - of Information Mapping fame - claiming otherwise). The crucial difference is that with written instructions, you are not asking the reader to remember seven items (or steps, in this case). Readers will generally read one step, carry out this step, drop it from short-term memory, read the next step, carry it out, and so on. They are therefore being asked to remember exactly one thing at a time. If a task consists of twenty tasks, then they will likely remember one thing at a time, twenty times. The 7 +/- 2 rule simply does not come into play at all. So when writing user instructions, if a task consists of twenty consecutive tasks with no logical division (as can be the case when describing how to complete a single screen in some software applications - such as SAP), then have twenty tasks, numbered from 1 to 20. To try to impose some arbitrary grouping just to satisfy the 7+/- 2 rule will only confuse the reader (as they try to work out exactly why the steps were split where they were...).

Word choice

Use the imperative form of the verb

The imperative mood is used for instructions. By using the imperative form of the verb, you will ensure that your instructions instruct. Using the imperative form of the verb has the added advantage of implying that the instructions are commands that must be followed, and are not optional activities.

Examples:

Avoid Use Instead
The engine is started by turning the key clockwise. Turn the key clockwise to start the engine.
Completed forms should be passed to the Sales Manager for approval. Pass the completed form to the Sales Manager for approval.

Note that the actual title of the instruction does not normally follow this rule, but should use the gerund form of the verb (for example, "Starting the engine") - unless the instruction itself is one in a series of instructions.

In some cases it may be necessary to prefix the instruction with a qualifying clause indicating a time, condition, or place. For example:

  • When the green light flashes, turn the lever to the 'Off' position.
  • If the temperature rises above 78 degrees Farenheit, switch on the air conditioning unit.
  • Using a size 8 spanner, tighten the nut.
  • In the receiving application, enable Bluetooth visibility.

Use the present tense

Instructions are most often referred to when the task is being carried out. Therefore, you should always use the active voice in instructions. That is, give instructions as though they are about to be carried out immediately, and describe the results of these as though they had just happened.

Examples:

Avoid Use Instead
When you click Execute the report will be displayed on the screen. Click Execute.

Result:
The report is displayed on the screen.
When you want to execute the report you will click the Execute button Once you are ready to execute the report, click the Execute button.

Use the active voice

Any form of writing is clearer when the subject of the sentence is the person (or thing) carrying out the action indicated by the verb. From an instructional perspective, the use of the active voice makes the instructions more 'compelling'.

Examples:

Avoid Use Instead
The report can be run by clicking the Execute button. Run the report by clicking the Execute button. (Or better: Click the Execute button to run the report.)

Use the second person

Instructions are instructing a specific person - the person reading them. They should therefore always address that person. Therefore, you should write instructions as if you were speaking directly to the person who will be reading them. Note that it is not strictly necessary to write "You must turn the key..."; "You must" is implied, and so writing "Turn the key..." is usually sufficient (as for verbal instructions).

Never write instructions in the third person ("Users can start the engine by turning the key"). This is extremely bad form, as it implies that the person receiving the instructions is different to the person carrying them out. Using the third-person will also unsettle readers, causing them to question whether they (the users) should be reading the instructions or not.

Examples:

Avoid Use Instead
Users must check product availability before confirming the order. You must check product availability before confirming the order.

See also

Personal tools
Support