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. 2. 3. 4. 5. Press <F4>. Press <F2>. Press <enter>. Press <F2>. Press <enter>. 1. 2. 3. 4. 5. Hit <F4>. Press<F2>. Select <enter>. Press <F2>. 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. 2. 3. 4. 5. Press <F4>. Press <F2>. Press <enter>. Press <F2>. 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) b) c) d) e) You can copy your disk now by clicking the OK button. Click the OK button. Now, let’s click the OK button. The OK button can now be clicked. 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. b. c. d. After the operator has set appropriate flags, he can enter the debug mode. After the user has set appropriate flags, he/she can enter the debug mode. After the users have set appropriate flags, they can enter the debug mode. 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 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, crossreferencing and headings? What revisions need to be made in the Table of Contents? Language editing Items 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? Yes No Revisions to make

Yes

No

Revisions to make

6

Sign up to vote on this title
UsefulNot useful