PLANNING THE MANUAL
Writing a manual requires careful planning so that you communicate formation clearly and accurately using clear prose, effective page design, and visual aids. To plan effectively, you must consider the audience, analyze procedures and parts, select visual aids, format the pages, arrange the sections, and prepare for the review process.
Consider the Audience
The audience for Inoperative manual varies widely in knowledge and background. Some readers will be beginners with little or no technical knowledge others will be experienced. The person learning his first word processing progressiveness nothing about “save cut paste open close and print Readers learning their fifth program, however, already understand basic word-processing concepts. Often readers will use the manual in an emotionally charged situation: perhaps they have a deadline to meet and must fix the machine quickly. To help the audience, you must design the pages to allow easy access to the contents. Manual readers do not read the manual like a story – first page to last page. They select the section they need. As a result, you must use devices – such as heads and tables of contents – to make it easy to . find information.
Analyze the Procedures and Parts
Analyzing the procedures includes two activities: discovering all the procedures and analyzing the steps in each procedure. Usually engineers (who have designed and built the machine) assist writers in this stage. While the following discussion focuses on machines, most of what is said transfers easily to software, a common topic for manuals. (I am indebted to Cohen and Cunningham for this section).
Discover Procedures Discovering all the procedures requires that you learn the machine so thoroughly that you are expert enough to talk to an engineer about it. You must learn tu operate it, disassemble it, and fix it. You must learn the name and function. of each part. You must learn all the procedures the machine can perform and all the ways it performs them. These proedures may include
how to assemble it
how to start it
how to stop it
how to load it
how it produces its end product
how each part contributes to producing the end product
how to adjust parts for effective performance
how to change it to perform slightly different tasks,
For example, the writer of a manual for a piston-filler, a machine that inserts liquids into bottles, must not only learn how to start and stop the machine but also grasp how the machine injects the liquid into ‘the bottle. Gaining this knowledge requires observing the machine in action, interviewing engineers, and assembling and disassembling sections.
Analyze the Steps To analyze the steps in each procedure requires the same methodology as writing a set of instructions The writer determines both the end goal and the starting point of the procedure, and then provides the in-between steps to guide the users from start to finish. A helpful device for this analysis is a combination flow chart decision tree. Make a flow chart for the entire procedure, each step represented by a box, and then convert the chart to a decision tree. Here is part of a larger sequence of steps taken from the piston-filler manual. The object of the sequence is to explain how to insert a specified amount of liquid into a bottle. Figure 16.1 below shows the flow chart; on page 332 shows the decision tree based on the flow chart.
Here is the text developed from the two figures:
1. Set the fill distance for the proper volume.
a. Check specifications, p. 10, for bottle volumes .
b. To determine this distance, find out the diameter of your piston.
c. Go to volume chart on p. 11.
d. Fine the piston diameter in the left column.
e. Read across to the volume you need.
f. Read up to determine the length you need.
g. Adjust the distance “on A to B (Figure 6 [not shown]) to the length you need.
2. Add the product to the topper,
If you unsure of the product type, see specifications, p. 11.
3. Press the left button for single cycle.
Analyze the to analyze the par;.ts, list each important part and explain what it does. In general, you will set up a specific section where .you explain each part. A VCR manual, for instance, will have a section that .points out each part in the machine and describes its function .. Here is a sample of a part analysis; in this case the part is a stop button: The red emergency stop button immediately stops a/l functions of the machine.
Select Visual Aids
Manuals depend heavily on visual aids. Photographs, drawings, flow charts, decision trees, schematics, and troubleshooting charts are all used to help out the reader. As .you write the instructions, you’ must decide whether or not each step needs a visual aid. If you write a software manual, use a screen dump to illustrate your text. (A screen dump is a picture of exactly what appears on the screen.) Many manuals have at least one visual aid per page. Recently, manual writers have started to use one visual aid per step.
For illustrating steps, many manual writers use photographs and drawings. When writers employ large numbers of photograph sand drawings, they usually require assistance from, photographers and artists. The manual writer must carefully plan the visual image needed to illustrate the step. He or ‘She must decide which image to include and which angle to view it from. If the user will see the part the front, then a picture of it from the rear would be useless. Manual writers often. employ a storyboard, such as the one shown in to plan the visual aids.
Format the rages
The manual writer must design the manual’s pages to make them easy to read. Two basic concerns are laying out the page and choosing type sizes. Laying Out the Page Layout the page so that it is easy to- read, following the elements of formatting explained Two additional concepts will help here:
• Make a template
• Use a grid
A tell plate is art arrangement of as the elements that will appear on each page, Including page numbers, headers, footers, rules, and blocks of text. The page number should appear in an easy-to-find spot – usually the upper right corner. Headers and footers are the lines of type that appear .on each page, top and bottom. For example, you may want to put the name of the: process the header and the name of the chapter in the footer. If you use rules (thin lines drawn across the page), place a rule below a header and above a footer. Attention to these details will make a pleasing page.
A grid is a group of imaginary lines that divide. a page into rectangles. Designers use a grid to ensure that similar cements appear on pages in the same relative position and proportion. One common grid divides the page into three imaginary columns and four rows. Writers place text Lot he left and visuals to the right. shows two sample page grids.
Other grids and arrangements – are possible, as you will see if you compare several manuals. Two very good producers of manuals arc Apple
Computer and John Deere, Inc. A sample Apple page application Chapter (p. 12); selections from a John Deere page
Choosing type Size Manuals generally use 10-point type in the text. Typeset or laser-printed manuals have head systems of larger point sizes, usually boldfaced. Bold facing for heads is available on many word processing systems; heads in typed manuals usually are underlined.
Designating Levels of Heads As discussed in Chapter 7, YOll can designate head levels in two ways, numbered and open. The numbered organization uses headings and a rigid section-numbering system to identify each section clearly:
1.1.1 Sub part
1.1.2 Sub part
1.2.1 Sub part’
1.2.2 Sub part
Many long manuals. especially those written for the military, use this method of organization The open organization uses headings of various sizes and various locations on the page to indicate divisions. In this method, common in consumer user manuals anJ in many computer manuals, the first level might be IS point bold centered, the second, 14 point bold at the left margin. J\ boldface system might use the following levels:
Arrange the Sections
You must decide on the order of the sections. these.
The basic principles are
• Always d)scribe a part, then tell how to use it.
• Always cross-reference; never assume the reader will have read an earlier section. Basically, a manual has two major sections:
• description of the parts (for example, the function of all the buttons on the control panel)
• instructions for all the procedures (how to start the machine from the control panel)
Outline the Review Process
A review process is a plan for having other knowledgeable people check the accuracy of the contents and the acceptability of the design. The usual. method is to write the text, then have another person or a group review it. In industrial situations, this person might be the engineer-who designed the machine, If you write for a client, It will be the client or some group designated by the client. Usually this process produces numerous changes and revisions, which you must incorporate into the text. After the text review, you usually have a design review so that everyone concerned agrees on the layout of the pages. You should show several possible layouts so your reviewers can select one. A~the outset of the project, set dates for each of these reviews, and decide who will be part of the review team.