WRITING THE MANUAL

WRITING THE MANUAL

The following student sample shows parts of an operator’s manual for software designed to repair payroll. The sections included here the introduction and the operation instructions  are essential ones used in all manuals. The full manual included a title page and a table of contents. This manual uses an open-head system.

Introduction

An introduction explains how to use the manual, gives appropriate background, and defines the subject of the manual appropriate, it states the level of training needed to use the mechanism, fur example, as pointed .out below, what basic concepts users need to know, Introductions also   any special information that will help familiarize readers with the equipment.

How to Use This Manual

This manual has three parts:

• The Introduction gives an overview of the program

•”Using the Payroll Program” explains how to use the program’s
12 procedures

• The Appendices show sample reports and related references. The following conventions are used in this manual:

• Bold type’ means to enter something

• Square brackets [ ] are used to identify a key that cannot be represented-by a single character.

For example Press {enter] to continue. This means you should press the [enter] key. . .

About the Pay roll Program

The payroll program  manage your student payroll. Information about each student employee is stored in a data base. From this data base you can print payroll labels, time cards, a budget report, and an employee list. How will the payroll program help you? It will allow you to keep an accurate and up-to-date record of your student employees. By entering the hours an employer works, you will be able to keep track of how much you are on student payroll. In short, you will have control  student payroll.

The Support Services Division has been using an older version of this program since 1982. It has been rewritten so that each campus operation can use it to manage its own student payroll. Similar programs are also being used in the Maintenance Office and Leisure Center.
The following conventions are used in the program:

• The date is displayed in the upper left corner of the screen.

• Your location in the program is displayed in the upper right corner of the screen. For example, when you are at the Main Menu screen, “Main Menu” will be displayed.

What You Need to Know About the [enter] Key

The [enter] key has two functions:

• It completes an entry of data into a field. When an instruction tells you to enter data, you then need to complete the entry by striking the [enter] key. For example, “Enter the last name” means you should type in the last name and then strike the [enter] key.

• It tells the program your answer to a question. When an instruction tells you to press a key, you only need to strike that key. For example, “Press [enter] to continue” means you should strike the [enter] key if you want to continue. Before You Use the Program Before you use the program, you should

a. have a basic understanding of data bases, i.e., know what a record and field are

b. be familiar with an IBM PC, its keyboard, and how to use diskettes ,.

c. know how  set up, start  and use your printer

What You NeEld to Start the Program

To start and use the program you will need:

• an IBM PC or IBM-compatible with a printer

• the Start up Diskette

• the Files Diskette

• the Backup Diskette

Operation

The operation section explains each process that the user must follow. Directions for operation should be divided into short, numbered, easy-to follow sequences. Within the directions, refer to components by their call out numbers to help the readers locate controls and gauges. All manual writers must be aware of the dangers associated with running a machine. Keep in mind that if you leave out a step, the operator will probably not catch the error, and the result might be serious. Also, you must warn readers about potentially dangerous operations by inserting the word ballgame in capital letters and by providing a short explanation of the danger. These warnings should always appear before the actual instruction.

The following pages present one section from a small software program manual.

USING THE PAYROLL PROGRAM

This section will enable you to start the Payroll Program and use it.from the Main Menu. To start the program:

1. Insert the Start up Diskette in drive A (the left drive).

2. Insert the Files Diskette in drive B (the right drive).

3. Turn on the computer, monitor, and printer if the system is off. Press [ctrl] [al] simultaneously as soon as the system is on.

4. Wait for the computer to boot up and for the files to be loaded into memory.

Note: The name of each file will be displayed on the screen. Do not press any keys until you are prompted at the bottom of the screen.

5. Press [K] to assent to the License Agreement.

6. If you do not want to continue with the program, press [ctrl] c. You will end the program and return to the A: pro,})pt.

7. Pres you will be taken to the Main Menu

The Report Sub menu

Pressing G on the Main Menu will take you to the Report Sub menu From this menu, you can generate and print the budget report and the employee report, print the employee list, and enter the budget data. From the Main Menu. you will be able to generate and print the budget report. Use 8 1/2-inch by t t-inch paper in the printer. To generate and print the budget report:

1. Press G from the Main Menu for Generate and Print Reports.

1

2. Press B from the Report Sub menu for Generate and Print the Budget Report.

3. Press'[enter] to return to the Report Sub menu If you do not want to continue. Note: After you start step 4, you cannot exit until the Budget Report has been printed. .

4. Put a 1/2-inch by t t-lnch paper in the printer and align the print head with a page perforation.

5. Put the printer in character draft mode by

a. turning the printer off

b. waiting ten seconds

c. turning the printer back on

Note: You can skip this step if you have already done it In another procedure.

6. Press R to print just the Budget Report. Press R to generate and print the, budget Report Note: When you generate the Budget Report, data already entered in the Enter Hours for the Pay Period procedure will be compiled. You should only generate the report once per pay period.

7. Return to the Report Sub menu after the budget report has been printed. Then press X to exit to the Main Menu from the Report Sub menu.

Entering the Budget Data

From the Main-Menu, you will be able to enter the budget data. The data are taken (room the control sheet for student payroll.

To enter the budget data:

1. Press G from the Main Menu for Generate and Print Roberts.

2. Press E from the Report Sub menu for Enter the Budget Data.

3. Press-Y to keep the year-to:date totals. Press X to reset the year-to-date totals to.zero.

4. Press ‘[enter} if the data are correct. You can correct an error by pressing Z and reentering the data.

5. You wilt return to the Report Sub menu after pressing [enter], Then press X to exit to the Main Menu from the Report Sub menu.

SUMMARY

This chapter explains how to plan and write a manual. The’ writer must choose his or her audience level, stating in the introduction about the knowledge level of the user. When planning a manual, it is essential is that the writer thoroughly learn the processes and parts of the machine to be described. Helpful visual aids and pages designed for easy reading also must be planned early in the writing process. The general plan of a manual is (l) to describe the parts and their function, and (2) to explain the steps in till’ procedures. The writer also should provide an introduction (with background, warnings, and any special information a user must know) and a conclusion (with maintenance procedures: a troubleshooting list, and so forth).

MODEL

The professional model that follows includes many sections, though not all, of an operator’s manual for a piston filler.

PISTON FILLING PRINCIPLE

In the pneumatic piston filling system, the amount of product discharged from the hopper into the container is controlled by the length of the piston stroke. Using the capacity chart in the appendix, you may establish the proper piston stroke length to discharge the appropriate amount of product. Once the-stroke length is set, each cycle of the piston will discharge the same amount of product into the container placed under the nozzle~ On the intake stroke valve plug opens to the hopper and the proper amount of product is pulled the cylinder. As the feed stroke begins, the valve plug rotates and closes off.the hopper. The valve plug is then open to the fill tube. On the discharge stroke, the piston pushes the product through the cylinder and discharges’ it into the container.

HOW TO INSTALL YOUR PISTON FllER

1. Remove the upper structure of the crate, leaving the unit bolted to the skids.

2. Examine the unit for possible shipping damage, such as loose parts.

3. Check to be sure your kit includes a spanner wrench for cylinder removal, and a piston wrench

4. II there is no damage, move the unit on the skids to your production area ..

5. Connect the unit to your air supply.

6. Set the piston filler regulator at 40-60 psi  Most products  use 40 psi. Set the to 60 psi for procucts that have 3 heavier consistency

1

SETTING THE CONTROLS

Your pneumatic piston filler will accurately discharge a fixed volume of flowable product into a container. You must adjust the valves for product discharge air flow * control and the air cylinder retract stroke to set the speeds of the forward and retract strokes. You must also adjust the length of the piston stroke to control the amount of product discharged into the container.

Adjusting the Product Discharge Air Flow

1. Rotate the yellow valve plug to control the product discharge flow.

a. For a faster product discharge, rotate the valve counterclockwise to a higher ~mber, lining up the number on the valve with the red line.

b. For a slower product discharqe, rotate the valve clockwise to a lower numbedining up the number on the valve with the red line.

c. This valve should be set at approximately the same value as the retract stroke (B on Fig. 3). Adjusting the Air Cylinder Retract Stroke

1. Rotate the yellow valve plug (8 on Fig. 3) to control the speed of the retract stroke.

a. For a faster retract stroke, rotate the valve counterclockwise to a higher number, lining up the number on the valve with the red line.

2. The  two yellow valves located closer to the hopper are factory set and do not to be adjusted. Setting the Piston Stroke Length

1. Using the capacity chart in the appendix, look down the left-hand column for the diameter of your cylinder.

2. Follow across the row to locate the number of ounces you wilt be using.

3. When you have found the correct number of ounces, look at the top of the column to find the stroke length.

4. Measure the stroke length from point A to point B as shown on Figure.

1

1

OPERATING PROCEDURES

Your pneumatic piston filler has two different cycle settings:

1. A single cycle, which will complete one cycle and then stop.

2. An automatic cycle, which will provide a continuous cycle until you stop it. In order to familiarize yourself with the two cycles, make a dry run with the t,wo types of cycles before beginning production. Single Cycw. Operation

To make a dry run:

1. Set the selector switch  in the downward position.

2. Pull out the red emergency stop button

3. Push in the green start button The machine will complete one cycle, filling one container, and then will stop automatically.

4. Observe the rate of the product discharge stroke and the retract stroke. Make any adjustments necessary to increase or decrease the speeds of the strokes.

5. Add your product to the hopper.

6. Place the container under the nozzle.

7. Push the green button and the machine will fill the container.

CLEANING

Your piston filler should be cleaned after production is completed. or.it you are changing to a different type of product. The cleaning procedure is done in two phases:

1. Flushing out the system.

2. Cleaning the valve.

Flushing put the System

1. Run the machine until the hopper is empty. ~.

2. Fill the hopper with soapy water or appropriate cleaning solution.

3. Place a large container or bucket under the nozzle.

4. Set the machine for automatic cycle.

5. Continue to cycle the machine until the hopper is empty.

6. Stop the machine by pushing in the red emergency stop button.

7. Add clear rinse water to the hopper.

8. Start the automatic cycle and continue to cycle the machine until the water
runs clear. adding more water if necessary.

Cleaning the Valve

1. Disconnect the piston filler from the plant air supply.

2. Remove the piston:

a. Remove the two hand knobs.

b. Using the spanner wrench provided, loosen the piston cylinder.

c. Grasp the air cylinder and slide it out to. the right.

d. Grasp the piston cylinder and slide it out to the right.

3. Remove the two hex nuts that hold the nozzle to the valve.

4. Remove the nozzle.

5. Clean the nozzle with soapy water. Rinse and wipe dry.

6. Disassemble the valve plug.

a. Remove the pin arm.

b. Remove the spring Clip.

c. remove the four bolts that are holding the end plate. I Flush out all the parts with soapy water or appropriate cleaning solution. Rinse and wipe dry.

EXERCISES

1. Examine two or three operator’s manuals. Use all the same kind if possible – sewing machines, VCRs, electrical generators, computers, osdlloscopes, electronic microscopes, whatever. If you cannot find several of the same type, use any three manuals. Analyze the manuals for page layout, use of visual aids, number and arrangement of sections, and style: Depending on your instructor’s assignment, perform one of the following: (1) Write a brief persuasive memo to convince your manager at work to accept one of the formats. (2) Prepare a five-minute speech in which you explain why one format among the two or three is best. Use visual aids to explain your position.

2. Prepare a troubleshooting chart for a machine or process that you know well.

WRITING ASSIGNMENT

1. Write an operator’s manual. Choose ;fny machine you know well – or would like to learn about. The possibilities are numerous – a bicycle, a sewing machine, part of a software program such as Words tar or Lotus 1-2-3, a computer system, any laboratory device, a welding machirie. Because of the difficulty of the assignment, your instructor will advise you on the type of visual aids to use. If you need to use high-quality photographs or drawings, you may need assistance from another student who has the necessary skills. Your manual must include at least an introduction, a table of contents, a description of the parts.

WORK CITED

Cohen, Gerald, and Donald H. Cunningham. Creating Technical Manuals: A Stepby- Step Approach to Writing User-Friendly Manuals. New York: McGraw, 1984.instructions for procedures. You might also include a troubleshooting section. Do not forget to give warnings when appropriate.

PLANNING THE MANUAL

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.

1

1

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.0 SECTION
1.1 COMPONENT
1.1.1 Sub part
1.1.2 Sub part
1.2 COMPONENT
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.

Operator’s Manuals

Operator’s Manuals

PLANNING THE MANUAL

WRITING THE MANUAL

Manuals are a common and extremely important type of technical writing. Companies sell not only the mechanisms they manufacture but also the knowledge tc use those products properly. hilt knowledge takes the form of a manual. Both the manufacturer and the buy want a manual that will ensure safe and successful assembly, operation, maintenance, and repair of the mechanism. Extremely complex mechanisms have separate manuals for assembly, check-out, operation, and so on – and sometimes. several volumes for each. The most common kind of manual. however, is the operator’s manual which must be written for virtually all mechanisms. Operator’s manuals have two basic sections: descriptions of the functions of the parts, and sets of instructions for performing the machine’s various processes. In addition, the manual also gives information concerning theory of operation, warranty, specifications, parts lists, and locations of dealers (Qr advice or parts. This chapter will explain how to plan and write an operator’s manual.