Markel Instructions Technical Communication 11th Ed

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 17

Download
Open PDF In Browser	View PDF

Writing Instructions

551

FIGURE 20.4
(continued)
With a parallel hybrid electric vehicle, both the engine and the electric motor
generate the power that drives the wheels. The addition of computer controls
and a transmission allow these components to work together. This is the
technology in the Insight, Civic, and Accord hybrids from Honda. Honda calls it
their Integrated Motor Assist (IMA) technology. . . . Since the engine is connected
directly to the wheels in this setup, it eliminates the inefficiency of converting
mechanical power to electricity and back, which makes these hybrids quite
efficient on the highway. Yet the same direct connection between the engine
and the wheels that increases highway efficiency compared to a series hybrid
does reduce, but not eliminate, the city driving efficiency benefits (i.e., the engine
operates inefficiently in stop-and-go driving because it is forced to meet the
associated widely varying power demands).
Series/Parallel Drivetrains
This drivetrain merges the advantages and complications of the parallel and
series drivetrains. By combining the two designs, the engine can both drive the
wheels directly (as in the parallel drivetrain) and be effectively disconnected
from the wheels so that only the electric motor powers the wheels (as in the
series drivetrain). The Toyota Prius has made this concept popular, and a similar
technology is also in the new Ford Escape Hybrid. As a result of this dual
drivetrain, the engine operates at near optimum efficiency more often. . . .

Conclusion

Knowing what’s under the hood of hybrid electric vehicles will help you evaluate
the available choices in the market. Considering most major auto manufacturers
plan to release HEVs in the next few years, you’ll be ready to choose the right one
for you. Enjoy driving into the future.

This section of the description ends
with a brief conclusion.

FIGURE 20.4 Excerpt from a Mechanism Description (continued )

Writing Instructions
This section discusses instructions, which are process descriptions written to
help readers perform a specific task—for instance, installing a water heater
in a house.
Although written instructions are still produced today, the growth of social
media has radically changed how organizations instruct people on how to
use their products and services. Now that technology has made it easy for
people to participate in writing instructions and to view and make videos,
most organizations try to present instructional material not only as formal
written instructions but also through discussion boards, wikis, and videos.
And users do not rely exclusively on the organizations themselves to create
and present instructions. Rather, they create their own text and videos.
Most organizations do not see this participation as a threat. A 2012 survey
of more than 500 organizations (Abel, 2013) suggests that organizations are

20_MAR_7337_ch20_533-575.indd 551

11/10/14 11:00 AM

552

WRITING DEFINITIONS, DESCRIPTIONS, AND INSTRUCTIONS

FIGURE 20.5
Specifications
Source: Logitech, 2012: http://logitech
-en-amr.custhelp.com/app/answers
/detail/a_id/33976/~/logitech-ue
-9000-wireless-headphones-technical
-specifications. Used with permission of
Logitech.

An important kind of description
is called a specification. A typical
specification (or spec) consists of a
graphic and a set of statistics about
the device and its performance
characteristics. Specifications help
readers understand the capabilities
of an item. You will see specifications on devices as small as transistors and as large as aircraft carriers.

Because this web-based spec sheet
accompanies a consumer product,
the arrangement of the specs is
geared toward the interests of the
likely purchasers. The audio specs
are presented before the power
specs because potential purchasers of high-end headphones will
be most interested in the sound
quality.

20_MAR_7337_ch20_533-575.indd 552

11/10/14 11:00 AM

Writing Instructions

553

FIGURE 20.6 An Effective Process Description
Biochemical conversion uses
biocatalysts, such as enzymes,
in addition to heat and other
chemicals, to convert the
carbohydrate portion of the
biomass (hemicellulose and
cellulose) into an intermediate
sugar stream. These sugars are
intermediate building blocks
that can then be fermented or
chemically catalyzed into ethanol,
other advanced biofuels, and
value-added chemicals. The overall
process can be broken into the
following essential steps:
A. Feedstock Supply:
Feedstocks for biochemical
processes are selected for
optimum composition,
quality, and size. Feedstock
handling systems tailored to
biochemical processing are
essential to cost-effective,
high-yield operations.
B. Pretreatment: Biomass is
heated (often combined with
an acid or base) to break the
tough, fibrous cell walls down
and make the cellulose easier
to hydrolyze (see next step).
C. Hydrolysis: Enzymes (or other
catalysts) enable the sugars in
the pretreated material to be
separated and released over a
period of several days.
D1. Biological Conversion:
Microorganisms are added,
which then use the sugars
to generate other molecules
suitable for use as fuels or
building-block chemicals.

Source: U.S. Department of Energy, 2013:
www1.eere.energy.gov/bioenergy/pdfs
/biochemical_four_pager.pdf.

This description begins with an
overview of the process of biochemical conversion: the process of using
fermentation and catalysis to make
fuels and products.
The description includes a flowchart
explaining the major steps in the
process. The designers included
photographs to add visual interest
to the flowchart.
The lettered steps in the flowchart
correspond to the textual descriptions of the steps in the process.
Most of the description is written
in the passive voice (such as “Feedstocks for biochemical processes
are selected . . .”). The passive voice
is appropriate because the focus of
this process description is on what
happens to the materials, not on
what a person does. By contrast, in
a set of instructions the focus is on
what a person does.

D2. Chemical Conversion: Alternatively, the sugars can be converted to fuels or an
entire suite of other useful products using chemical catalysis.
E. Product Recovery: Products are separated from water, solvents, and any
residual solids.
F. Product Distribution: Fuels are transported to blending facilities, while other
products and intermediates may be sent to traditional refineries or processing
facilities for use in a diverse slate of consumer products.
G. Heat & Power: The remaining solids are mostly lignin, which can be burned for
heat and power.

20_MAR_7337_ch20_533-575.indd 553

11/10/14 11:00 AM

554

WRITING DEFINITIONS, DESCRIPTIONS, AND INSTRUCTIONS

trying to take advantage of it. Among the major survey findings are the following four:
r NPSFUIBOIBMGPGUIFSFTQPOEFOUTQSPWJEFBOPOMJOFTVQQPSUDPNNVOJUZ
based around discussion boards
r QFSDFOUPGSFTQPOEFOUTQSPWJEFPQQPSUVOJUJFTGPSVTFSTUPTIBSF
feedback and rank the company’s instructional material
r QFSDFOUPGSFTQPOEFOUTMFUVTFSTDSFBUFPSFEJUJOTUSVDUJPOTUISPVHI
wikis
r QFSDFOUPGSFTQPOEFOUTSFQPSUUIBUUIFJSVTFSTBSFDSFBUJOHUIFJSPXO
instructions and support forums, without the support of the respondents
Your first job, then, in presenting instructions is to devise a strategy for
incorporating user participation in the process and to choose the best mix
of media for encouraging that participation. Written instructions (whether
presented online or printed and put in the box with the product) will always
have a role because they are portable and can include as much detail as necessary for even the most complex tasks and systems. But consider whether
your users will also benefit from access to other people’s ideas (in a discussion board or wiki) or from watching a video.

UNDERSTANDING THE ROLE OF INSTRUCTIONAL VIDEOS
The explosive growth of YouTube and other video-hosting sites has revolutionized how instructions are created and used. Product manufacturers and
users alike make videos to help people understand how to perform tasks.
If you are producing instructional videos on behalf of your company, think
about what style of video will be most effective for your audience, purpose, and
subject. Companies often use simple, cartoon-style videos for basic conceptual
information (“what can you do with a microblog?”), screenshot-based videos
for computer-based tasks (“how to use master slides in PowerPoint”), and liveaction videos for physical tasks (“how to install a ground-fault interrupter”).
Video is particularly useful for communicating about physical tasks that
call for subtle physical movements or that involve both sight and sound.
For instance, a video would be more effective than written instructions in
communicating how a guitarist uses the tremolo bar to create different sonic
effects. The viewer can focus on the way the guitarist holds his or her hand
on the tremolo and on the range of movement that he or she uses. In addition, the viewer can hear how these physical actions change the sound.
Although there are many software tools available for making videos, making professional-quality videos calls for professional skills, experience, and
tools. If you are going to be making many videos, it makes sense to learn the
process and acquire professional tools and equipment; otherwise, consult your
company’s media department or consider hiring freelance video producers.
They can help you create videos that reflect positively on your organization.
Instructional videos tend to be brief. Whereas a reader of a document can
navigate easily among various parts or steps, viewers of a video can only

20_MAR_7337_ch20_533-575.indd 554

11/10/14 11:00 AM

Writing Instructions

hit play, pause, and stop. For this reason, you should break long tasks into a
series of brief videos: ideally 2–3 minutes, but no more than 12–15 minutes.
Give each one a clear, specific title so viewers can easily tell whether they
want to view it.
Similarly, you should make your instructional videos simple and
uncluttered. Software makes it easy to add a lot of cinematic effects, but
less is often more. Your purpose is not to win an Academy Award; it is to
help your audience learn how to carry out a task. The fewer distractions in
the video, the easier it will be for viewers to see what to do. And remember that video is a warm medium. Connect with the viewer by being
friendly, informal, and direct. Don’t say, “Next, the right mouse button is
pushed.” Say, “Press the right mouse button.” But do not confuse being
warm and informal with not needing to prepare. You do need to plan,
write a script, and rehearse.
Be sure to build in the time and resources to revise the video. As discussed
in Chapter 13, good technical communication calls for reviewing, revising,
and testing. This concept applies to video. Start testing even before production. Make sure your script and visuals are right for your audience and
purpose. And repeat the process after you have created the rough cut of the
video and after each major revision.
Use other sources responsibly. You need to obtain written permission to
use any copyrighted text, images, videos, or music that will appear in your
video. Because this process can be lengthy, difficult, and expensive, many
organizations have a simple standing rule: do not use any copyrighted material. Instead, they generate their own images and text, and even their own
music.

555

For more about usability testing, see
Ch. 13, p. 348.

DESIGNING A SET OF WRITTEN INSTRUCTIONS
As you plan to write instructions, think about how readers will use them.
Analyzing your audience and purpose and gathering and organizing your
information will help you decide whether you should write a one-page set of
instructions or a longer document that needs to be bound. You might realize
that the information would work better as a web-based document that can
include videos, be updated periodically, and provide readers with links to the
information they need. Or you might decide to write several versions of the
information: a brief paper-based set of instructions and a longer, web-based
document with links.
As always in technical communication, imagining how readers will
use what you write will help you plan your document. For example, having decided that your audience, purpose, and subject call for a printed set
of instructions of perhaps 1,000 words and a dozen drawings and photographs, you can start to design the document. You will need to consider your
resources, especially your budget: long documents cost more than short
ones; color costs more than black and white; heavy paper costs more than
light paper; secure bindings cost more than staples.

20_MAR_7337_ch20_533-575.indd 555

For more about planning, see Ch. 3.

11/10/14 11:00 AM

556

WRITING DEFINITIONS, DESCRIPTIONS, AND INSTRUCTIONS

Designing a set of instructions is much like designing any other kind of technical document. As discussed in Chapter 11, you want to create a document that
is attractive and easy to use. When you design a set of instructions, you need to
consider a number of issues related to document design and page design:
r What are your readers’ expectations? For a simple, inexpensive product,
such as a light switch, readers will expect to find instructions written on
the back of the package or printed in black and white on a small sheet of
paper folded inside the package. For an expensive consumer product, such
as a high-definition TV, readers will expect to find instructions in a more
sophisticated full-color document printed on high-quality paper.
r Do you need to create more than one set of instructions for different
audiences? If you are writing about a complex device such as an electronic
thermostat, you might decide to create one set of instructions for
electricians (who will install and maintain the device) and one set for
homeowners (who will operate the device). In addition to producing paper
copies of the documents, you might want to post them on the Internet,
along with a brief video of the tasks you describe.
r What languages should you use? In most countries, several languages are
spoken. You might decide to include instructions in two or more languages.
Doing so will help you communicate better with more people, and it can
help you avoid legal problems. In liability cases, U.S. courts sometimes find
that if a company knows that many of its customers speak only Spanish, for
example, the instructions should appear in Spanish as well as in English.
You have two choices for presenting information in multiple languages:
simultaneous presentation or sequential presentation. In a simultaneous
design, you might use a multi-column page on which one column presents
the graphics, another presents the text in English, and another presents the
text in Spanish. Obviously, this won’t work if you need to present information
in more than two or three languages. But it is efficient because you present
each graphic only once. In a sequential design, you present all the information
in English (say, on pages 1–8), then all the information in Spanish (on
pages 9–16). The sequential design is easier for readers to use because they
are not distracted by text in other languages, but you will have to present the
graphics more than once, which will make the instructions longer.
r Will readers be anxious about the information? If readers will find the
information intimidating, make the design unintimidating. For instance,
if you are writing for general readers about how to set up a wireless
network for home computers, create open pages with a lot of white space
and graphics. Use large type and narrow text columns so that each page
contains a relatively small amount of information. Figure 20.7 illustrates
the advantages of an open design.
r Will the environment in which the instructions are read affect the document
design? If people will be using the instructions outdoors, you will need
to use a coated paper that can tolerate moisture or dirt. If people will be
reading the instructions while sitting in a small, enclosed area, you might

20_MAR_7337_ch20_533-575.indd 556

11/10/14 11:00 AM

Writing Instructions

557

select a small paper size and a binding that allows the reader to fold the
pages over to save space. If people have a lot of room, you might decide to
create poster-size instructions that can be taped to the wall and that are
easy to read from across the room.
FIGURE 20.7
Cluttered and
Attractive Page Designs
in a Set of Instructions

a. Cluttered design

b. Attractive design

This page is cluttered, containing far too
much information. In addition, the page
is not chunked effectively. As a result, the
reader’s eyes don’t know where to focus.
Would you look forward to using these
instructions to assemble a cabinet?

This page is well designed, containing an appropriate
amount of information presented in a simple twocolumn format. Notice the effective use of white
space and the horizontal rules separating the steps.
Reprinted by permission of Anthro Corporation.

Reprinted by permission of Slide-Lok.

Designing Clear, Attractive Pages
To design pages that are clear and attractive, follow these two guidelines:
Create an open, airy design. Do not squeeze too much information onto the
page. Build in space for wide margins and effective line spacing, use large type,
and chunk the information effectively.
Clearly relate the graphics to the text. In the step-by-step portion of a set of
instructions, present graphics to accompany every step or almost every step. Create a design that makes it clear which graphics go with each text passage. One
easy way to do this is to use a table, with the graphics in one column and the text
in the other. A horizontal rule or extra line spacing separates the text and graphics for one step from the text and graphics for the next step.

20_MAR_7337_ch20_533-575.indd 557

For more about chunking, see
Ch. 11, p. 260.

11/10/14 11:00 AM

558

WRITING DEFINITIONS, DESCRIPTIONS, AND INSTRUCTIONS

PLANNING FOR SAFETY
If the subject you are writing about involves safety risks, your most important responsibility is to do everything you can to ensure your readers’
safety.

ETHICS NOTE
ENSURING YOUR READERS’ SAFETY
To a large extent, the best way to keep your readers safe is to be honest and write clearly. If
readers will encounter safety risks, explain what those risks are and how to minimize them.
Doing so is a question of rights. Readers have a right to the best information they can get.
Ensuring your readers’ safety is also a question of law. People who get hurt can sue the company that made the product or provided the service. As discussed in Chapter 2, this field
of law is called liability law. Your company is likely to have legal professionals on staff or on
retainer whose job is to ensure that the company is not responsible for putting people at
unnecessary risk.

When you write safety information, be clear and concise. Avoid complicated sentences.
COMPLICATED

It is required that safety glasses be worn when inside this laboratory.

SIMPLE

You must wear safety glasses in this laboratory.

SIMPLE

Wear safety glasses in this laboratory.

Sometimes a phrase works better than a sentence: “Safety Glasses Required.”
Because a typical manual or set of instructions can contain dozens of
comments—some related to safety and some not—experts have devised
signal words to indicate the seriousness of the advice. Unfortunately, signal
words are not used consistently. For instance, the American National Standards Institute (ANSI) and the U.S. military’s MILSPEC publish definitions that
differ significantly, and many private companies have their own definitions.
Figure 20.8 presents the four most commonly used signal words. The first
three signal words are accompanied by symbols showing the color combinations endorsed by ANSI in its standard Z535.4.
Whether safety information is printed in a document or on machinery
or equipment, it should be prominent and easy to read. Many organizations
use visual symbols to represent levels of danger, but these symbols are not
standardized.
Organizations that create products that are used only in the United States
design safety information to conform with standards published by ANSI and
by the federal Occupational Safety and Health Administration (OSHA). Organizations that create products that are also used outside the United States
design safety information to conform with standards published by the International Organization for Standardization (ISO). Figure 20.9 shows a safety
label that incorporates both ANSI and ISO standards.

20_MAR_7337_ch20_533-575.indd 558

11/10/14 11:00 AM

Writing Instructions

SIGNAL WORD

EXPLANATION

EXAMPLE

Danger

Danger is used to alert
readers about an immediate
and serious hazard that will
likely be fatal. Writers often
use all uppercase letters for
danger statements.

DANGER: EXTREMELY HIGH
VOLTAGE. STAND BACK.

Warning

Warning is used to alert
readers about the potential
for serious injury or death
or serious damage to
equipment. Writers often
use all uppercase letters for
warning statements.

WARNING: TO PREVENT
SERIOUS INJURY TO YOUR
ARMS AND HANDS, YOU
MUST MAKE SURE THE ARM
RESTRAINTS ARE IN PLACE
BEFORE OPERATING THIS
MACHINE.

Caution

Caution is used to alert
readers about the potential
for anything from moderate
injury to serious equipment
damage or destruction.

Caution: Do not use
nonrechargeable batteries in
this charging unit; they could
damage the charging unit.

Note

Note is used for a tip or
suggestion to help readers
carry out a procedure
successfully.

Note: Two kinds of washers
are provided—regular
washers and locking
washers. Be sure to use the
locking washers here.

559

FIGURE 20.8 Signal Words

Part of planning for safety is determining the best location for safety information.
This question has no easy answer because
you cannot control how your audience
reads your document. Be conservative: put
safety information wherever you think the
FIGURE 20.9 A Typical
reader is likely to see it, and don’t be afraid
Safety Label
to repeat yourself. A reasonable amount
Source: Clarion Safety Systems, 2013: www
of repetition—such as including the same
.clarionsafety.com/Electrical-Hazard-Safety-Labels.
safety comment at the top of each page—is
effective. But don’t repeat the same piece
of advice in each of 20 steps, because readers will stop paying attention to it.
If your company’s format for instructions calls for a safety section near the
beginning of the document, place the information there and repeat it just
before the appropriate step in the step-by-step section.
Figure 20.10 shows one industry association’s guidelines for placing safety
information on conveyor belts.

20_MAR_7337_ch20_533-575.indd 559

The yellow triangle on the left is
consistent with the ISO approach.
Because ISO creates standards for
international use, its safety labels
use icons, not words, to represent
safety hazards.
The signal word ”Danger” and
the text are consistent with the
ANSI approach. The information is
presented in English.

11/10/14 11:00 AM

560

WRITING DEFINITIONS, DESCRIPTIONS, AND INSTRUCTIONS

To be located on conveyors where there
are exposed moving parts which must
be unguarded to facilitate function, i.e.
rollers, pulleys, shafts, chains, etc.

Moving equipment
can cause severe
injury

To be placed along both sides of these
conveyors since these conveyors provide
surfaces and profiles attractive, but
hazardous, for climbing, sitting, walking,
or riding.

Climbing, sitting,
walking or riding on
conveyor at any time will
cause severe
injury or death
KEEP OFF

To be placed on removable guards to warn
that operation of the machinery with guards
removed would expose chains, belts, gears,
shafts, pulleys, couplings, etc. which create
hazards.

Exposed moving
parts can cause
severe injury
LOCK OUT POWER
before removing guard

This page shows the four safety
labels that the industry association
recommends for use on conveyor
belts.
The diagram of the conveyor belt
shows where the organization recommends placing the safety labels.

Servicing moving or
energized equipment
can cause severe
injury
LOCK OUT POWER
before servicing

FIGURE 20.10 Placement of Safety Information on
Equipment
Source: Conveyor Equipment Manufacturers Association, 2004. Reprinted by permission of
Conveyor Equipment Manufacturers Association.

DRAFTING EFFECTIVE INSTRUCTIONS
Instructions can be brief (a small sheet of paper) or extensive (20 pages or
more). Brief instructions might be produced by a writer, a graphic artist, and
a subject-matter expert. Longer instructions might call for the assistance of
others, such as marketing and legal personnel.
Regardless of the size of the project, most instructions are organized like
process descriptions. The main difference is that the conclusion of a set of
instructions is not a summary but an explanation of how readers can make
sure they have followed the instructions correctly. Most sets of instructions

20_MAR_7337_ch20_533-575.indd 560

11/10/14 11:00 AM

Writing Instructions

561

contain four elements: a title, a general introduction, step-by-step instructions, and a conclusion.

Drafting Titles A good title for instructions is simple and clear. Two forms
are common:
r How-to. This is the simplest: “How to Install the J112 Shock Absorber.”
r Gerund. The gerund form of a verb is the -ing form: “Installing the J112
Shock Absorber.”
One form to avoid is the noun string, which is awkward and difficult for readers to understand: “J112 Shock Absorber Installation Instructions.”

For more about noun strings, see
Ch. 10, p. 235.

Drafting General Introductions The general introduction provides the
preliminary information that readers will need to follow the instructions
safely and easily.

Drafting Introductions for Instructions
Every set of instructions is unique and therefore calls for a different introduction.
Consider answering the following six questions, as appropriate:
Who should carry out this task? Sometimes you need to identify or describe the
person or persons who are to carry out a task. Aircraft maintenance, for example,
may be performed only by those certified to do it.
Why should the reader carry out this task? Sometimes the reason is obvious:
you don’t need to explain why a backyard barbecue grill should be assembled.
But you do need to explain the rationale for many tasks, such as changing antifreeze in a car’s radiator.
When should the reader carry out this task? Some tasks, such as rotating tires or
planting seeds, need to be performed at particular times or at particular intervals.
What safety measures or other concerns should the reader understand? In addition to the safety measures that apply to the whole task, mention any tips that
will make the job easier:
NOTE: For ease of assembly, leave all nuts loose. Give only three or four
complete turns on bolt threads.
What items will the reader need? List necessary tools, materials, and equipment
so that readers will not have to interrupt their work to hunt for something. If you
think readers might not be able to identify these items easily, include drawings
next to the names.
How long will the task take? Consider stating how long the task will take readers
with no experience, some experience, and a lot of experience.

20_MAR_7337_ch20_533-575.indd 561

For more about graphics, see Ch. 12.

11/10/14 11:00 AM

562

WRITING DEFINITIONS, DESCRIPTIONS, AND INSTRUCTIONS

Drafting Step-by-Step Instructions The heart of a set of instructions is
the step-by-step information.

Drafting Steps in Instructions
Follow these six suggestions for writing steps that are easy to understand.
Number the instructions. For long, complex instructions, use two-level numbering, such as a decimal system:
1
1.1
1.2
2
2.1
2.2
etc.
If you need to present a long list of steps, group the steps logically into sets and
begin each set with a clear heading. A list of 50 steps, for example, could be
divided into 6 sets of 8 or 9 steps each.
Present the right amount of information in each step. Each step should define
a single task the reader can carry out easily, without having to refer back to the
instructions.

For more about the imperative mood
and the passive voice, see Ch. 10,
pp. 230 and 231.

TOO MUCH INFORMATION

1. Mix one part cement with one part water,
using the trowel. When the mixture is a thick
consistency without any lumps bigger than a
marble, place a strip of the mixture about 1″
high and 1” wide along the face of the brick.

TOO LITTLE INFORMATION

1. Pick up the trowel.

RIGHT AMOUNT OF INFORMATION

1. Mix one part cement with one part water,
using the trowel, until the mixture is a thick
consistency without any lumps bigger than a
marble.
2. Place a strip of the mixture about 1” high and
1” wide along the face of the brick.

Use the imperative mood. The imperative mood expresses a request or a
command—for example, “Attach the red wire.” The imperative is more direct and
economical than the indicative mood (“You should attach the red wire” or “The
operator should attach the red wire”). Avoid the passive voice (“The red wire is
attached”), because it can be ambiguous: is the red wire already attached?
Do not confuse steps and feedback statements. A step is an action that the
reader is to perform. A feedback statement describes an event that occurs in response to a step. For instance, a step might read “Insert the disk in the drive.” That
step’s feedback statement might read “The system will now update your user
information.” Do not present a feedback statement as a numbered step. Present
(continued)

20_MAR_7337_ch20_533-575.indd 562

11/10/14 11:00 AM

Writing Instructions

563

it as part of the step to which it refers. Some writers give all feedback statements
their own design.
Include graphics. When appropriate, add a photograph or a drawing to show the
reader what to do. Some activities—such as adding two drops of a reagent to a
mixture—do not need an illustration, but they might be clarified by a chart or a
table.
Do not omit articles (a, an, the) to save space. Omitting articles can make the
instructions unclear and hard to read. In the sentence “Locate midpoint and draw
line,” for example, the reader cannot tell if “draw line” is a noun (as in “locate the
draw line”) or a verb and its object (as in “draw a line”).

Drafting Conclusions Instructions often conclude by stating that the
reader has now completed the task or by describing what the reader should
do next. For example:
Now that you have replaced the glass and applied the glazing compound, let the
window sit for at least five days so that the glazing can cure. Then, prime and paint the
window.

Some conclusions end with maintenance tips or a troubleshooting guide. A troubleshooting guide, usually presented as a table, identifies common problems
and explains how to solve them.

REVISING, EDITING, AND PROOFREADING INSTRUCTIONS
You know, of course, to revise, edit, and proofread all the documents you
write to make sure they are honest, clear, accurate, comprehensive, accessible, concise, professional in appearance, and correct. When you write instructions, you should be extra careful, for two reasons.
First, your readers rely on your instructions to carry out a task. If they
can’t complete it—or they do complete it, but they don’t achieve the expected
outcome—they’ll be unhappy. Nobody likes to spend a few hours assembling
a garage-door opener, only to find half a dozen parts left over. Second, your
readers rely on you to help them complete the task safely. To prevent injuries
and liability actions, build time into the budget to revise, edit, and proofread
the instructions carefully. Then, if you can, carry out usability testing on the
instructions.

For more about usability testing, see
Ch. 13, pp. 348–53.

A LOOK AT SEVERAL SAMPLE SETS OF INSTRUCTIONS
Figure 20.11 is an excerpt from a set of instructions. Figure 20.12 on page 565
shows a list of tools and materials from a set of instructions. Figure 20.13 on
page 566 is an excerpt from the safety information in a set of instructions.
Figure 20.14 on page 567 is a portion of the troubleshooting guide in the
instructions for a lawnmower. Figure 20.15 on page 567 is an excerpt from a
thread in a discussion board.

20_MAR_7337_ch20_533-575.indd 563

11/10/14 11:00 AM

564

WRITING DEFINITIONS, DESCRIPTIONS, AND INSTRUCTIONS

This page from the user’s manual for
a tablet computer used in healthcare environments discusses how to
use the barcode scanner.
Note that the writer uses a gerund
(-ing phrase) in the major heading
to describe the action (“Using the
barcode scanner”).
The writer explains why readers
might want to scan barcodes.
The writer lists the types of barcodes the tablet can scan and then
explains how to enable the tablet to
scan additional types. Note that the
more conceptual information about
the task precedes the instructional
information. Why? Because readers
want to understand the big picture
before getting into the details.
The writer presents the steps. Note
that the writer numbers the steps
and uses the imperative mood for
each one.
The drawing helps readers understand how to hold the tablet and
aim it at the barcode. In cases such
as this, simple drawings work better
than photographs because they do
not distract readers with unnecessary detail.

FIGURE 20.11 Excerpt from a Set of Instructions
Source: Motion Computing, 2013: http://www.motioncomputing.com/downloads/User_Docs/C5F5-Series/C5teF5te
-UserGuide_Win8_EN.pdf. Courtesy Motion Computing.

20_MAR_7337_ch20_533-575.indd 564

11/10/14 11:00 AM

Writing Instructions

565

Drawings of tools, materials, and
parts are more effective than lists.

FIGURE 20.12 List of Tools and Materials
Courtesy of General Electric Corporation.

20_MAR_7337_ch20_533-575.indd 565

11/10/14 11:00 AM

566

WRITING DEFINITIONS, DESCRIPTIONS, AND INSTRUCTIONS

FIGURE 20.13 Excerpt
from Safety Information
HEALTH AND SAFETY INFORMATION
You must read the following warnings before you set up or use the Orion 35 3D
game system. If young children will be using this product, a competent adult
must read and explain this safety information to them. Otherwise, these children
could be injured.
Also, you must carefully read the instruction booklet for the game you are
playing to learn additional health and safety information.
This excerpt from a user manual for
a video-game player that displays
3D images describes two of the
safety risks associated with playing
video games.

! followed by WARNING, CAUTION, or
In this manual, you will see this symbol ▲
IMPORTANT.
Here is what these three words mean:
!
▲

WARNING Describes an action that could lead to a serious personal injury or
death.

!
▲
Notice that the excerpt uses
mandatory language: “You
must . . . .” Although politeness is
desirable most of the time, you
don’t want to sound as if you were
making suggestions or asking readers to do you favors. For instance, if
a task calls for using safety goggles,
do not write “You should consider
wearing safety goggles.” Instead,
write “You must wear safety goggles
when operating this equipment.”
This set of safety information
defines the keywords warning, caution, and important.

CAUTION Describes an action that could lead to personal injury or damage
to the Orion 35 3D game system, games, or accessories.

!
▲

IMPORTANT Describes an action that could lead to damage to the Orion 35
3D game system, games, or accessories.

!
▲

WARNING The 3D Feature May Be Used Only by Children 7 and Older

Children age 6 or younger who watch 3D images can suffer vision damage. You
must use the Parental Control feature (see page 36) to prevent the system from
displaying 3D images when children 6 or younger are using the system.
!
▲

WARNING Seizures

For a small percentage of people (approximately 1 in 4000), light flashes and
patterns can cause seizures or blackouts. TV programs and videos can include
these light flashes and patterns.
Anybody who has ever had a seizure, loss of awareness, or any other symptom
linked to epilepsy must check with a physician before playing any video game.
Always watch your children when they play video games. Stop the game and
consult a physician if your child has any of the following symptoms:
t $POWVMTJPOT
t &ZFPSNVTDMFUXJUDIJOH
t -PTTPGBXBSFOFTT
t "MUFSFEWJTJPO
t *OWPMVOUBSZNPWFNFOUT
t %JTPSJFOUBUJPO
To reduce the chance that you or a child will have a seizure while playing video
games:

The safety information goes on to
discuss eyestrain and motion sickness, repetitive motion injuries, and
radio frequency interference.

20_MAR_7337_ch20_533-575.indd 566

1.
2.
3.
4.
5.

Sit or stand as far as possible from the screen.
Play the game on the smallest screen that is available.
Do not play any video game if you are tired.
Keep the room well-lit.
Every hour, take a break for 10 or 15 minutes.

11/10/14 11:00 AM

Writing Instructions

567

PROBLEM

CAUSE

CORRECTION

The mower does
not start.

1. The mower is out of gas.
2. The gas is stale.
3. The spark plug wire is disconnected from the
spark plug.

1. Fill the gas tank.
2. Drain the tank and refill it with fresh gas.
3. Connect the wire to the plug.

The mower
loses power.

1. The grass is too high.
2. The air cleaner is dirty.
3. There is a buildup of grass, leaves, or trash
in the underside of the mower housing.

1. Set the mower to a “higher cut” position. See page 10.
2. Replace the air cleaner. See page 11.
3. Disconnect the spark plug wire, attach it to the retainer post,
and clean the underside of the mower housing. See page 8.

FIGURE 20.14

Excerpt from a Troubleshooting Guide

Original post from a user:
I am having difficulty printing TIFF files from a Microsoft program onto 11 x 17 sized paper to
my WC 5335 [a Xerox printer]. When I print my file it will print only the 81/2 x 11 image on the
11 x 17 paper. I want the image to fill up the whole 11 x 17 page. When I print I select fit to
size, but I still get the same thing. Has anyone ever experienced this situation? Does anybody
have any tips on how I can resolve this issue? Thanks.
Reply from the Xerox representative monitoring the forum:
Thank you for using the Support Forum. Please take a look at this solution for printing to
11 x 17 sized paper and see if it relates to your issue. If this does not help please consider
contacting your support centre for further assistance.
Thanks.
Response from a second user:
Yup indeed, I agree. And I also want to share you some information about TIFF: TIFF,
originally called Tagged Image File Format, is a computer file format for storing images,
including photographs, line art among graphic artists, the publishing industry, and both
amateur and professional photographers in general.
TIFF format is supported widely in industry image processing applications, such as
Photoshop (Adobe), GIMP (Jasc), PhotoImpact and Paint Shop Pro (Ulead) and Desktop
publishing & Page Layout applications, like QuarkXPress and Adobe InDesign. Other
applications, like scanning, faxing, word processing, OCR and more applications also support
TIFF format. You can choose a TIFF processing SDK whose way of processing is simple
and fast to process TIFF files. I am testing with the related SDKs. I hope we can have some
communication later. Good luck.
Response from a third user:
Thanks for sharing, that’s awesome but somewhat overpriced for me who will just use it only
once. Do you have some cheaper or even free versions? Any suggestion will be appreciated!
Response from a fourth user:
I suggest you have a look at Gimp; it’s open source and free.

This excerpt from a user-support
group on the Xerox website shows
the way many organizations collaborate with their customers to
help solve customer problems.
In the original post, a customer
explains a problem he or she is
having printing a TIFF file with a
Xerox printer.
The Xerox representative, who
monitors the user forum, directs the
customer to the company’s statement that is intended to solve the
user’s problem.
A second user recommends the
Xerox representative’s reply and
presents additional information
about TIFF files. Notice in the last
sentence that he or she offers to try
to stay in touch with the customer
who asked the original question.
A third user, who is experiencing
the same problem that the first user
wrote about, expresses appreciation
for the second user’s suggestions but
raises a concern about the cost of the
alternatives he or she describes.

FIGURE 20.15 Excerpts from a Thread in a Customer-Support Forum
Many companies use customer forums as an efficient and effective way to help their users solve problems.
Although the forums can be messy—and sometimes users write nasty things about the company—companies
realize that letting users participate greatly increases the chances that they will find solutions to their problems.
Source: Xerox Corporation, 2013: http://forum.support.xerox.com/t5/Printing/TIFF-files/td-p/21986. Used by permission of
Xerox Corporation.

20_MAR_7337_ch20_533-575.indd 567

A fourth user responds by pointing
out that GIMP, one of the alternatives listed by the second user, is a
free program.

11/10/14 11:00 AM

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
Page Count                      : 17
Title                           : Markel - Instructions - Technical Communication (11th Ed)(gnv64)
Author                          : Mike Markel
Subject                         : 
Producer                        : Mac OS X 10.8.5 Quartz PDFContext
Creator                         : Preview
Create Date                     : 2017:06:29 03:22:54Z
Modify Date                     : 2017:06:29 03:22:54Z
Apple Keywords                  :

EXIF Metadata provided by EXIF.tools

Markel Instructions Technical Communication 11th Ed

Navigation menu

Versions of this User Manual:

Views

Navigation