CSCI 2100 - 09 Instructions and User Manuals

CSCI 2100– Lecture #9
Instructions and User Manuals
JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR
1
LAST CLASS – BUSINESS LETTERS
• The Structure of a Business Letter

• Common Mistakes
• Types of Business Letters
• Written Assignment #1 & Presentation Assignment #2
JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 2

TODAY’S AGENDA
Three things for today:
Writing Instructions
User Manuals
Technical Instructions

WRITING INSTRUCTIONS
How will I know that you understand?

You will be able to write clear, properly worded
instructions
I’m assuming that you already know…

Knowing your audience, writing concisely, and avoiding
ambiguity.

Do we need instructions?
If so, why?
What purpose do instructions

serve?
Source: https://www.safety-label.co.uk/products/refer-to-instructions-symbol-label

PROCEDURE
A procedure describes how

something is done:
Distance is measured with electronic
meter DME 297.

INSTRUCTION
An instruction tells reader what to do:

Measure the distance with electronic
meter DME 297.

Instructions use the Imperative Mood:
Disengage the gear, then start the
engine.
Avoid wishy-washy words: should, could,

would, might, may:
The gear should be disengaged before
starting the engine.
BE SPECIFIC
What is wrong?
Cut the wire into an appropriate length

for each connection and strip a short
piece of insulation from each end. Install
the wire between the correct terminals
and pins.
Cut a 0.62 m length of 10-guage wire
and strip 20 mm of insulation from each
end. Solder one end of the wire to
terminal 7 and the other end to pin 19.

HOW TO BEGIN
It’s okay to start with an introductory
or conditional phrase:
Before connecting the meter to the
power supply, set all the switches to
“zero”.

AVOID AMBIGUITY
There is no room in technical instructions
for ambiguity.
Do not write something that can be taken
more than one way.
Replace vague references (“relatively
high”, “near the top”, “an adequate
supply”) with clearly started
measurements or quantities.

WHAT’S AMBIGUOUS?
“Align the trace so that it is inclined
approximately 30º to the horizontal.”
“Approximately” and “to the horizontal” are
both ambiguous
“Align the trace so that it is inclined 30º
(±2º) above the horizontal.”

SHORT IS GOOD
Keep steps short.
Do not make them overly complex.

IF IT’S TOO COMPLICATED…
If step is complicated, divide it into a
major step and a series of sub-steps.
Number them accordingly:
3. List the supporting documents in
block J of Form 658. Sign the form
and distribute as follows:
3.1 Attach the supporting
documents…

Insert precautions whenever you need to
warn readers of dangerous conditions or of
potential damage if they do no exercise care.
Source: https://news.bitcoin.com/fork-watch-take-extra-precaution-when-trying-to-access-post-fork-tokens/

Draw attention to precautions by drawing a box
around them, indenting text on both sides.
Source: http://www.safetylabelsolutions.com/Warning--Electric-Shock-Hazard_p_398.html

WARNING & CAUTION
WARNING: Alerts readers to an

element of personal danger.
CAUTION: Tells readers when

care is needed to prevent
equipment damage.

Does every precaution carry the same weight?
Source: https://www.wwaytv3.com/2017/03/17/huge-five-alarm-fire-burns-in-downtown-raleigh/

SUGGESTED PRECAUTIONS
DANGER: Serious threat to life or health.
WARNING: Potential damage to product
or minor injury.
CAUTION: Risk to proper performance.
NOTE: Additional explanation, possible
problem
(Henwood, 2007, p. 183)

Make sure that you put your precaution
BEFORE the step to which it refers.
It’s little help after!
OPERATIONAL CHECK
Usability tests of instructions are

essential.
Give instructions to someone of roughly
equal knowledge as final user.

OBSERVE
Observe how well person performs the

task.
Do not interrupt or guide them.
Note hesitations or difficulties.

CLARIFY AND AMEND
When task is complete, ask if any step

needs clarification.
Rewrite ambiguous steps.
Recheck with another new person.
Repeat until readers can follow
instructions easily.

Releasing instructions
without testing them could
be highly hazardous to your
organization’s reputation and
your career.
Source: https://www.amazon.com/Warning-ANSI-Message-Heavy-Aluminum/dp/B07F62551Q

SUMMARY
Instructions must be short, unambiguous
imperatives.
Precautions have different levels and

must come before, not after, the step it
refers to.
Do an operational check on instructions
before releasing them

Source: https://cemarking.net/user-manual-part-ce-marking/


You will be able to write proper user manuals.

Writing Instructions.

USER MANUALS USUALLY HAVE
Brief description of the product.

Instructions on how to use it.
Suggestions for fixing problems.
Assumes reader has slight technical
knowledge.

USER MANUAL AUDIENCE
Identify your audience and their level
of knowledge about the product
Important in any writing; mandatory in
user manuals.
Instructions often written by technical
person.
Usually too complex and/or incomplete
from a reader’s viewpoint.
USER MANUALS - IMPORTANT
User manuals structured in
sequential order.
Outline is user-focused, task-
oriented.
Use clear, simple language.
Remember, the user often has limited
technical knowledge.

WRITING PLAN FOR USER MANUAL
Summary
Explain what the product is and what it can do.
Product Description
Operating
Instructions
Troubleshooting
Techniques

Summary
Product Description
Explain what the product consists of.
Operating
Instructions
Troubleshooting
Techniques

Summary
Product Description
Operating
Instructions Provide step-by-step instructions for the various
tasks the user will perform with the product.
Troubleshooting
Techniques

Summary
Product Description
Operating
Instructions
Troubleshooting
Techniques Explain how to remedy problems that may arise.

CREATING OPERATING
INSTRUCTIONS
Identify the audience.

Perform a task analysis.
Group and label each task.
Write the steps for each task.

TASK ANALYSIS – COMPREHENSIVE
List everything that users might want

to do with the product.
Focus on tasks users will perform,
not on what the product can do.

GROUPS AND LABEL TASKS
Review list of tasks from Task

Analysis.
Assign tasks to groups they fall into.
Organize groups into logical
sequence for intended audience.

WRITE THE STEPS
Write instructions to accomplish task.

Instructions are steps user needs to
perform in order to accomplish task.

EACH STEP
Each step must be a short,
numbered instruction (imperative
mood):
1. Click on the File Menu.
2. Choose Connect to the Server.
3. When a dialogue appears, enter your
ID and password.

TROUBLESHOOTING
Tell the reader what to do if

equipment doesn't work.
Consists of short, numbered steps
with verb in imperative mood.

Source: The IT Crowd

SUMMARY
User manuals are written for non-
technical users.
Have tasks users will want to perform, not

what the product can do.
Tasks (gerunds, “-ing”) are made up of

steps (instructions, imperatives).

TECHNICAL INSTRUCTIONS

You will be able to write properly formatted technical
instructions.

Writing Instructions.

Have detailed instructions, such as

service and repair procedures.
Assume reader is a technical expert.

Technical instructions tell someone to

do something.
Could define what has to be done,
leaving time/method up to reader or
step-by-step details stating exactly
what must be done, when, by whom.

Define your readers.

Establish their level of technical
knowledge, familiarity with the
subject.
This helps decide the depth of detail
needed.

If equipment is new, be detailed:

Find the hinged cover plate at the
bottom rear of the cabinet. Open it by
inserting a Robertson No. 2 screwdriver
into the narrow slot just above the hinge
and then rotating the screwdriver half a
turn counter-clockwise.

But if reader is familiar with subject:

Open cover.

WRITING PLAN FOR TECHNICAL
INSTRUCTIONS
Summary
Explain what has to be done.
Product Description
Operating
Instructions
Troubleshooting
Techniques

INSTRUCTIONS
Summary
Product Description
Explain why it has to be done.
Operating
Instructions
Troubleshooting
Techniques

INSTRUCTIONS
Summary
May combine in a single

paragraph.
Product Description
Operating
Instructions
Troubleshooting
Techniques

INSTRUCTIONS
Summary
Product Description
Operating
Instructions List any equipment needed. Pictures of tools can
help
Troubleshooting
Techniques

EXAMPLE

INSTRUCTIONS
Summary
Product Description
Operating
Instructions
Troubleshooting
Techniques Explain in short, authoritative steps how the
work is to be done.

SUMMARY
Technical instructions explain a task that

must be performed
They are written for technical people.
Use a summary, purpose, tools, steps

format.

WHAT IS THE VALUE?
 Usable instructions help an organization reduce
support costs
 Good documentation can enhance the reputation of
an organization
 User manuals can help people do their jobs and
make them more effective
 Effective communication can cut down on
misunderstandings
 Good technical communication makes YOU more
valuable to your organization
Source: https://www.youtube.com/watch?v=ycITF6yeBhQ

QUESTIONS?

REFERENCES
Blicq, R. & Moretto, L. (2012). Technically-Write!. Toronto: Pearson Canada
Inc.
Henwood, D. (2007). A Writing Guide for IT Professionals. Toronto: Oxford

University Press.
Lannon, J. & Klepp D. (2012). Technical Communication, 5th Cdn. Edition.

Toronto: Pearson Canada Inc.

CSCI 2100 - 09 Instructions and User Manuals

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CSCI 2100 - 09 Instructions and User Manuals

Uploaded by

Copyright:

Available Formats

CSCI 2100– Lecture #9

Instructions and User Manuals

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR

• The Structure of a Business Letter

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 2

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 3

How will I know that you understand?

I’m assuming that you already know…

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 4

What purpose do instructions

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 5

A procedure describes how

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 6

An instruction tells reader what to do:

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 7

Avoid wishy-washy words: should, could,

Cut the wire into an appropriate length

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 9

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 10

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 12

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 13

Keep steps short.

Do not make them overly complex.

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 14

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 16

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 17

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 19

WARNING: Alerts readers to an

CAUTION: Tells readers when

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 20

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 21

(Henwood, 2007, p. 183)

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 22

Usability tests of instructions are

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 25

Observe how well person performs the

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 26

When task is complete, ask if any step

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 27

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 28

Precautions have different levels and

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 29

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 30

How will I know that you understand?

I’m assuming that you already know…

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 31

Brief description of the product.

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 32

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 34

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 35

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 36

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 37

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 38

Identify the audience.

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 39

List everything that users might want

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 40

Review list of tasks from Task

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 41

Write instructions to accomplish task.

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 42

JANUARY 25, 2019, PRESENTED BY STACEY TAYLOR 43

Tell the reader what to do if