SECTION VII

EDITING TO ENSURE READABILITY

================================================================
Points to cover:
• use of language
• use of symbols + conventions

When you have completed drafting your manual, read it again to revise the contents
to check if needs further revision. Make use of the following checklist:

Is there any ambiguity or mistakes in any of your explanations or instructions,

including those in the appendices?

Is there any unnecessary repetition which reduces the conciseness of your

writing? Are there any bugs in the instructions?

Are the responses accurately described?

Have all essential cautions and warnings been included?

Is there any important information missing, including essential graphics,

cross-referencing and headings?

What revisions need to be made in the Table of Contents?

Check your use of language to ensure that effectiveness and readability have been
achieved. This section concerns the style of language that you should use in writing
various parts of a user manual.

VII.1 USE OF LANGUAGE

The you-tone
A you-tone can increase the ‘user-friendliness’ of your manual.
e.g.,
‘In this section, you will....’ or ‘This chapter introduces how you can ...’ ()
‘In this section, XXX will be discussed’ (, or not recommended)

The use of imperative/command verbs

Use the imperative verb for actions that you instruct your user to take. Imperatives
are primarily used in instructions or commands.
e.g.,
Click the right button. ()
Now, you can click the right button. ()

Simple and short sentence structures

Use simple sentence structures to ensure readability of instructions.
e.g.,
There is one major program in the application: MONITOR. ()
1
 Monitor is the major program in the application. ()

The use of a non-sexist tone

Use a pronoun or a noun that does not suggest a particular gender of the user (quite
often male). This is to avoid the impression that only males use the product.
e.g.,
If the user clicks the right button, he can see... (not recommended)
On clicking the right button, the user can see. ()

Consistent choices of words

Use consistent verbs or nouns to refer to actions or objects in order to avoid
confusion.
e.g.,
() ()
1. Press <F4>. 1. Hit <F4>.
2. Press <F2>. 2. Press<F2>.
3. Press <enter>. 3. Select <enter>.
4. Press <F2>. 4. Press <F2>.
5. Press <enter>. 5. Hit <enter>.

Preciseness in instructions
Leave no room for unnecessary speculation of instructions or explanations. Pay
special attention to the use of modal verbs. See table below for reference.

Meanings of different modal verbs: a quick guide for user manual writing

Modal verbs usual meanings in user guides

should/need • strong recommendation/requirement of carrying out an
important step. e.g., You should/need to obtain a password
first ...
• an assumption statement of what is expected to have happened
e.g., By now, you should have finished all the work..; You
should have received one formatting disc, one mouse, a user
guide and...
may, can • an option
e.g., You may exit the file now. (e.g., if you want to)
must/ have • an obligation
to / need to e.g., You must turn off the printer before opening the cover.
You have to report to your supervisor in case of ...

Consistent style of writing throughout

Whenever a document involves more than one writer, the style of writing may
become inconsistent. Make sure the style is edited to show consistency throughout.

VII.2 USE OF SYMBOLS AND CONVENTIONS

2
Bulleting and Numbering
Present lists of items vertically and bullet each item on a list. e.g.,

The proc routine returns and error 300 to the main program
under either of the following conditions:
• the record control field does not contain an X,Y or Z.
• the control word does not indicate the expected file
type.

Number all steps and present them vertically. e.g.,

1. Press <F4>.
2. Press <F2>.
3. Press <enter>.
4. Press <F2>.
5. Press <enter>.

Use of icons, font styles, and other symbols

Where possible, use icons or pictures to represent certain objects that the user needs
to handle on the screen. e.g., Click twice. Try to use differentiate characters or
numbers that the user need to key in from the names of function keys on the
keyboard. e.g.,
Type F 1 . (meaning to type in the two separate characters of ‘F’ and ‘1’)
Press <F1>. (the brackets here indicate that it is the function key F1)

Don’t forget to supply a key to the symbols and conventions used in the preface.

Use of graphics to reduce wordiness

One language feature of user manuals is conciseness. Short sentences and short
paragraphs are much preferred to long-winded discussion. Conciseness can also be
achieved by use of graphics to explain complicated concepts and especially elements
on a screen. Remember a picture can say a thousand words. It’s not a cliché but a
rule in user manuals. Refer to Secion IX for rules of how to introduce and make
references to graphics.

3
 Section VII -- Tasks File

Task 1 Choice of sentence structures in instructions (1)

From the following group of sentences, choose one which is the most
suitable in style for use in a set of instructions on how to copy a disk.
Justify your answer.

a) You can copy your disk now by clicking the OK button.

b) Click the OK button.
c) Now, let’s click the OK button.
d) The OK button can now be clicked.
e) Please click the OK button.

Task 2 Choice of sentence structures in instructions (2)

Study the following pairs of sentences and decide which in each
pair has a better (easy-to-follow) sentence structure. Justify your
answers.

1a. There is one major program in the application: MONITOR.

1b MONITOR is the major program in the application.

2a. No zeros to the right of the decimal point are suppressed.

2b. Zeros to the right of the decimal point are not suppressed.

3a. Program A can call five I/O routines.

3b. There are five I/O routines that can be called by Program A.

4a. Readers, be they experts or parvenus, seasoned or novice, desire

user manuals that may be effectively utilized, and moreover, are
handsome in appearance.
4b. Experts as well as beginners want user manuals that are easy to
use and look professional.

Task 3 Friendly and non-sexist tone

Which of the following is the best choice? Justify your answers.

a. After the operator has set appropriate flags, he can enter the debug mode.
b. After the user has set appropriate flags, he/she can enter the debug mode.
c. After the users have set appropriate flags, they can enter the debug mode.
d. After setting the appropriate flags, you can enter the debug mode.

Task 4 Consistent command words throughout for actions / objects

Study the following set of instructions and comment on their
consistency.
1.Hit F4.
2.When the prompt appears, strike the Return Key.
3.Select the first choice (See Fig. 4).
4.Press Enter again to save the file.

4
Task 5 Ensuring readability of long list of items
Decide which writing style in the following pair of paragraphs is a
better choice. 1a or 1b? Justify your answers.

1.a. When the PROC routine reads a record with a control field that
does not contain an X, Y, or Z, or in which that control word does
not indicate the expected file type, the routine returns an error
300 to the main program, which in turn displays the message text
and aborts the job.

1.b. The PROC routine returns and error 300 to the main program
under either of the following conditions:
•
the record control field does not contain an X, Y, or Z.
•
The control word does not indicate the expected file
type.
The main program in turn displays the error 300 message and
aborts the job.

Task 6 Consistent writing style throughout

Study the two extracts below written by two different writers of
the same manual. Can you notice any difference(s) in the style of
writing? What are they? What would you do if you were writers?

Writer 1
Columns 1 through 5 are reserved for optional statement numbers. Statement
numbers are not required, but if used, they cannot be duplicated within the
program. Statement numbers need not appear in ascending numeric sequence.
A maximum of 200 statement numbers can be used in one program. Statement
number positioning is shown in figure 9-3.

Writer 2
The directive portion of a statement can appear in columns 6-65. If a
statement exceeds column 65, you can continue the statement in column 6 of
the next line. When you continue a directive, you must include an asterisk (*)
in column 1 of the continued line. (Please refer to diagram 9-4).

Task 7 Leaving no room for unnecessary speculation (effective use of

modals and numbers)
Study the following two groups of sentences and decide the
best alternative in each of the groups. Justify your
answers.
1a. Click your mouse several times to ...
b. Click your mouse twice to...
c. Click your mouse successively twice...

2a. Now you can save your work on several other discs just in case.
b. Now you should save your work on at least one other disc in case of any
damages to the original one.
c. Now save your work on at least one other disc in case ....

Task 8 Edit your own draft (Part of Assignment 4)

Make use of the checklists provided on p.VII-6 to help you revise and
edit the language used in your first draft.

5
Checklists for your first draft

Contents
Items Yes No Revisions to make
Is there any ambiguity or mistakes in
any of your explanations or instructions,
including those in the appendices?
Is there any unnecessary repetition which
reduces the conciseness of your writing? Are
there any bugs in the instructions?
Are the responses accurately described?
Have all essential cautions and warnings
been included?
Is there any important information missing,
including essential graphics, cross-
referencing and headings?
What revisions need to be made in the Table
of Contents?

Language editing
Items Yes No Revisions to make
Have I used the you-tone effectively?
Have I used imperatives properly in
instructions?
Have I used simple and short sentences
throughout?
Have I used non-sexist language?
Have I used consistent language throughout?
(terms and tone)
Have I bulleted non-step lists?
Have I used enough graphics?
Have I labelled and referred to all graphics?