SECTION V
STRUCTURING A SECTION
& WRITING INSTRUCTIONS
================================================================
Points to cover:
 organization of a section
 contents and organization of a set of instructions
 follow-up tasks
 collective vs component steps
 supplying examples
 supplying graphics
With your Table of Contents ready, you can start to draft the contents of the major
sections. In this section you will learn the principles of organizing a section or a subsection in a computer user manual, and how to write effective instructions.
V.I
ORGANIZATION OF A SECTION (or A CHAPTER)
Most computing user manuals have the following sectional structure:
I.
Section / Chapter Head (e.g., Introduction to Excel at the XXX Institute
An introductory paragraph(s)
I.1
Sub-section Head 1 (e.g., Some basic features of Excel)
An introductory paragraph(s)
Main paragraph 1
Main paragraph 2
Main paragraph 3
…
I.2
Sub-section Head 2 (e.g., Prerequisites)
An introductory paragraph(s)
Main paragraph 1
Main paragraph 2
Main paragraph 3
…
I.3
Sub-section Head 3 (e.g., Entering Excel from Staff LAN menu)
An introductory paragraph(s)
Main paragraph 1
Main paragraph 2
Main paragraph 3
…
V-1
Note that each section (or chapter) consists of different tiers of sub-sections. Usually
each tier and section are assigned a decimal number, e.g., I.0 for a major section tier
and I.1, I.2, I.3, etc. for its sub-sections. Each section must be supplied with a clear
and focused section head. And each section at any level must begin with an
introductory text. Some sections might just carry explanations of some features,
terms, concepts, regulations or prerequisites whereas some sections might carry
important instructions only.
V.2
INTRODUCTORY TEXTS IN A USER MANUAL
Every section or sub-section in a manual begins with an introductory text. An
introductory text, be it at the section or sub-section or even sub-sub-section level, does
the following:
1.
2.
3.
4.
5.
announces the purpose(s) / topic of the section
justifies the topic (need, benefits, undesirable consequences resulted if nothing
related to the topic is done)
announces areas to cover in the section or the structure of the section if the
introductory text is at the major section level
presents background information crucial to the comprehension of the details
depicted in the section (e.g., explanations of one or two key terms to use, prerequisites that make the instructions workable, explaining some features on the
screen that the user need to operate when following your instructions)
cross-references other parts if some pre-requisite understanding is needed
before the user can understand the rest of the chapter
The higher level an introductory text appears, the more details of the above 5 types
will have to be given. (Refer to the Tasks 4 & 5 in the Tasks File of this section for
some samples of introductory text, which illustrate these various types of
information.) When you get down to a sub-section which only relates some brief
instructions, points 1-3 are the basic information that you should include.
V.3
WRITING INSTRUCTIONS
How to obtain information for instructions?
Deciding exactly what to explain and instruct (e.g., definitions, steps, warnings, etc.)
may not be as easy as you expect. First of all, being an IS professional does not
necessarily mean that you know the operation of every computing product. Second,
you may be able to operate a product very skilfully, but it does not mean that you are
conscious of them. As such, it may be quite difficult to articulate precisely and
concisely the instructions. Several tips are suggested here for you to collect
information to write instructions:
1.
2.
Consult existing manuals which are produced for a similar group of users. But
be very careful not to copy verbatim from these manuals.
Talk to experienced users or customer support analysts.
V-2
3.
4.
Use the product yourself and record the exact steps, responses, cautions,
possible problems, possible needs of explanation (e.g., names / terms /
positions of certain icons, etc.).
Talk to programmers or developers of the product
What exactly to explain and instruct, and why?
Unlike other kinds of writing, the contents and the organization of a set of instructions
in a computing user manual follow certain conventions, which aim at giving effective
explanations that might be all-too-obvious to a technical writer but complicated to
non-technical users. Always bear in mind that our ultimate aim of writing instructions
is to make sure that users can carry out all the essential actions to complete a task and
produce something correctly and efficiently by using the computing product.
In general, any set of instructions given in a tutorial user manual should carry the
following elements, which should appear in more or less the same order presented
here:








an introductory text announcing the beginning of a set of steps to follow
the purpose of the actions (the instructions) to take (e.g., to close the file, …)
a clear description of each of the actions to take (e.g., Click  twice.)
the response to the action taken for the user to check that the right step has been
taken
notes, cautions, warnings if possible risks or problems might occur if care is not
taken
(cross-referencing where an action may involve several sub-steps (e.g., saving a
file in a particular directory) which have been mentioned somewhere else already
but the user may have forgotten)
a supply of relevant examples where there is a need for them
a follow-up task for user to try out the steps described (e.g., Now, try to save your
own file on an appropriate dic) for a tutorial manual
Refer to Task 6 (Task File) for a set of instructions which illustrate some of these
elements.
V.4
COLLECTIVE vs COMPONENT STEPS
Sometimes what appears to be one step to a technical user is fact a series of sub-steps.
Take ‘saving’ as an example. It is a collective step, which is the general term used to
label a set of physical steps. This general name of the step in fact is defined by the
outcome, in this case having information securely placed on a disc. This big step
subsumes:
1.
2.
3.
4.
clicking the save icon or the File menu,
possibly creating a file name
choosing various options that follow
clicking the OK or the enter button.
V-3
These sub-steps are in fact the component steps of the action of ‘saving a file’. Find
out whether there is a need to give instructions for the component steps. The choice
depends on: the user’s technical background knowledge and whether the collective
step has been explained in a previous section. Cross-referencing may save the trouble
of repeating component steps if they have been mentioned somewhere already.
V.5
SUPPLYING EXAMPLES
Try to supply examples when explaining steps, terms or problems. Giving examples
is one effective way to explain an abstract or difficult concept. When supplying
examples, make sure they are relevant or familiar to your target user.
e.g.,
 When creating a file name, consider using a meaningful one, e.g., Essay 1 if it is a
file of your first essay to hand in.
 Create a password of 6 digits using characters, numbers or both (e.g., 971999 or
971AAA, or ABCDEFG)
 Don’t use common passwords (e.g., birthdays, your phone number, etc.)
V.6
SUPPLYING GRAPHICS
Where needed, provide pictures or images appearing on a corresponding screen to
illustrate your instructions (e.g., importing icons to click instead of giving names of
the icons) and responses (e.g., importing a screen that appears after an action). But
make sure the graphics are referred to and nicely blended into your writing. (Refer to
Section IX for various rules about the use of graphics.)
V.7
FOLLOW-UP TASKS IN TUTORIAL MANUALS
Follow-up tasks are very common in tutorial manuals. They are designed to allow the
user chances to practise skills or steps described in the manual. They either appear
right after a set of instructions or are put together in form of an exercise section at the
end of a section or sub-section. (For some examples, see the tasks in the tasks files of
this student manual.)
Some rules to remember when designing follow-up tasks:
 Design meaningful tasks and give meaningful of data for your user to work with.
If you want your user to learn saving a file, instruct the user to create a meaningful
name for the file and save it on his/her floppy disc if the user is a student using the
facilities at CSC.
 Instruct clearly. But remember that the instructions are not on how to complete
the tasks, which should have been given in your major sections. The instructions
are more on what you want the user to produce at the end. e.g., ‘Now prepare a
handout which you will use in your lectures. Add a header of your choice to the
handout.’
 Supply headings as you do to other sections or sub-sections
 Keep all practice tasks short. One to two tasks per set of skills will suffice.
V-4
Section V -- Tasks File
Task 1
Chapter structure: some organizing principles
Glance through Chapter One of Novel NetWare Networks and answer
the following questions:
a) What does the chapter cover? How many sections do you predict
this chapter comes with? Where did you find the answer?
b) How many sections are supplied in the handout? What are they?
c) How many sub-sections are there at least in each of the sections?
d) What does each section and sub-section begin with?
e) Can you represent the organization of the chapter schematically?
Task 2
Why do I need to learn how to give instructions?
Situation A:
An alien arrived from Mars, where creatures are barefooted. As a host
to this creature, you feel the need to buy it a pair of shoes and show it
how to wear them. The creature understands very little English, or any
language spoken on earth. Prepare a set of instructions that you will
use to show it how to put the shoes on. Your instructions will later be
tried out on the alien (acted out by some of your classmates).
Situation B:
A gweilo has just moved to Hong Kong. He does not know how to
use chopsticks. Write a set of steps to show him how to use the
utensil. Your instructions will later be tried out on the gweilo (acted
out by some of your classmates).
Task 3
Where and how can the writer obtain the exact details for a
manual?
You may have a skeleton of the manual worked out but might not
know the exact procedures or the detailed information to flesh out the
skeleton. For instance, you have decided that the user of your manual
needs instructions for accessing a system, and that you need to devote
one section to just these steps. But, you don’t know the steps yourself.
What would you to do find them out?
V-5
Task 4
Introductory text at a major section level (1)
Here is an introductory text of a section and one of its sub-section
from a manual on how to use the DeskJet 500C printer. Read it and
identify the lettered information given in this text.
II.
Using the HP DeskJet Series Printer Driver for Microsoft Windows 3.0
(section heading)
c) The instructions in this section will get you started using Microsoft Windows 3.0
with your HP deskJet 500C printer and the HP DeskJet Series Printer Driver for
Microsoft Windows 3.0.
b) To use your HP DeskJet Series Printer Driver for Microsoft Windows 3.0, you will
need learn how to perform the following tasks:

installing the driver and its support files on your hard disk

selecting printer settings

… (the list goes on)
II.1
Installing the HP DeskJet Series Printer Driver for Microsoft Windows
3.0
c) Two disks came with your printer:

the HP DeskJet Series Printer Driver Installation Disk 1

the HP DeskJet Series Printer Driver Installation Disk 2
Install your printer driver using the steps below:
1.
Start Windows 3.0 and ensure that no memory resident programs are
running.
2.
Open the Main group window.
c) __________________________________________________________________
b) __________________________________________________________________
c) __________________________________________________________________
d________________________________________________________________________________
V-6
Task 5
Introductory text at a sub-section level (2)
Study the introductory paragraph in the following, which is a sub-section
taken from Using LAN Without Tears. Identify the lettered information.
6.12
Setting up Personal Network Menu
(a) The ‘Make Personal Menu’ utility is provided as a network option under the
Network Environment Services Menu. (b) Through this option, you can create a
customized personal menu containing the menu options of your own choice.
(c)The system will bring up the personal menu as the first menu when the PC is
booted up.
(b)The utility also enables you to modify the existing personal menu at any time
and the revised menu will become effective when the menu system is reloaded.
(d) Procedures for creating the Personal Menu ... (the procedures are given from
this point on)
a) ___________________________________________________________________
b) __________________________________________________________________
c) __________________________________________________________________
d) __________________________________________________________________
Task 6
Elements of instructions
1. Study the following example of instructions. Identify the types of
information each of the lettered parts relates.
Procedures for creating the Personal Menu
1. (a) Select ‘Make Personal Menu’ from the Network Environment Services
Menu. c) A two-window display will appear. The upper window will
contain initially the Departmental Stand software Library Menu options,
while the bottom window will show the options of the personal menu if it
exists. The active option will be shown highlighted or in a different
colour.
2.
(a)Press the Up or Down arrow key (b) to locate the option you want to add
to your personal menu.
3.
(a) Press <F2> to select. (c) The option will be appended to the personal
menu and appear in the bottom window.
4.
(a) Repeat Step 2-3 to add other options. (c) Notice that the options will be
sorted in alphabetical order when the personal menu is brought up.
V-7
a) _________________________________________
b) _________________________________________
c) _________________________________________
Task 7
Responses in instructions
1.
Why are responses of actions needed in instructions?
2.
Which kinds of responses are better in user manuals, visual
images or a written description? Justify your answers.
Task 8
Collective step vs. component step of a collective step
1. Sometimes a step can mean more than one stroke on the keyboard.
For example, how many steps are actually involved in each of the
following three steps and what are they exactly?



saving a Word 6 document?
blocking?
cut and paste?
2. Which of the above three steps need be broken down into sub-steps
for the user of a manual on Word 6? Justify your answer.
Task 9
Notes / cautions / warnings
How do the words notes, cautions and warnings differ from each
other? Where should they be placed? in footnotes? next to the step
involved? Justify your answer.
Task 10
Practise writing your instructions (Assignments 3 & 4, individual
work)
Choose a section or sub-section from your ToC that includes some
instructions. Write the introductory text of the section, and the
instructions. Submit it as an assignment. Make use of the following
worksheet to guide your planning and writing.
Revise your work. Check to see if you have
 included a useful introductory text
 included the necessary steps, examples, responses, cautions and
warnings, etc.
Also, edit and proofread your work carefully. Check to see if you have
 made any mistakes listed on the error symbol sheet given on p.IV-9
 have numbered all your steps
 used imperatives throughout for the steps
V-8
Worksheet for planning your instruction-writing
Framework
Key information
Introductory
Text
1.
2.
3.
4.
5.
Instructions
Additional information
(cross-referencing,
cautions, warnings,
suggestions, tips, graphics )
What in general will be discussed in this
chapter?
Why is the information to cover needed?
What are some prerequisites for reading this
chapter?
How is this chapter structured?
What terms need be explained here?
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
V-9