The “How To” of “How To`s”: Writing Procedures Like a Pro
Contents
1. Always has an implied second person you they focus or a modified second person focus but never a third person the user focus the county you ABC Company we focus Uses the indicative mood regular Uses the imperative mood commands Use statements The technician traced or will the mouse pointer to trace the line from left to trace the line right e Sometimes uses the passive voice The file e Uses the active voice for actions taken by will be copied someone or something other than the user The software automatically copies the file Uses regular paragraph structure such as e Uses short often single sentence paragraphs topic sentence explanatory developing introduced by bullets or more commonly sentences numbers Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 21 Table 4 Process Description Versus Procedures A Process Description Procedural Writing Contains paragraphs that are organized e Contains bulleted or numbered items that are logically such as chronologically in organized chronologically sometimes with ascending or descending order of importance internal jumps and loops or some other way e Typically describes a fairly big picture e Contains technical gnat s eye details e Often integrates supplementary discussions Usually tells exactly what the reader will need about background justification alternatives for t2. Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 8 The Importance of Active Imperative Steps tTelling Them Where to Go 5 min One technique uses imperative sentences for actions the reader takes and declarative sentences for responses by the software the swing set the souffl or whatever is the receiver 1 PJH Press F2 to select the address list options of the action JSoft The screen displays the Options Menu You can even formalize this technique into a dialog structure which is helpful for entry level users Select the options you want to use Then press Enter The Importance of Parallelism TSOFT The son H H e soitware reorganizes Marching Two by Two 5 min the list according to the n you ve selected JSoft automatically Parallelism parallel structure is a technique of using the saves the new list as ADNEW TXT same types of words such as imperative verbs or the same in the default directory grammatical structure to emphasize similar items Press F7 to see and print the e All items in a list should have the same grammatical new address list structure In other words all items should be either fragments or complete sentences but no list should mix fragments and complete sentences JSoft The screen displays the new address list with print options at the bottom of the box e All headings of the same level sh
3. A Lifetime Guide to Flawless Business Writing Englewood Cliffs NJ Prentice Hall 1995 Hackos JoAnn and Dawn Stevens Standards for Online Communication New York John Wiley amp Sons 1997 Jones Dan Technical Writing Style Boston Allyn amp Bacon 1998 Microsoft Corporation Microsoft Manual of Style for Technical Publications 2nd ed Redmond WA Microsoft 1998 Novell Inc WordPerfect User s Guide Orem UT Novell 1994 Weiss Edmond How to Write Usable User Documentation Phoenix AZ Oryx 1991 Acknowledgment The presenters thank JoAnn Hackos Ph D for permission to use portions of her material in this document and in the workshop Dr Hackos is President of Comtech Services Inc 710 Kipling Street Suite 400 Denver Colorado 80215 phone 303 232 7586 email joann hackos comtech serv com Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 34 About the Presenters Rebecca Edgerton is the GIS documentation group manager for Woolpert LLP A senior STC member and long time STC presenter her technical documentation accomplishments over the last 20 years include database and software user manuals training materials implementation plans and policy and procedure manuals With more than two decades experience in technical writing Rebecca has won international national and local awards for the Woolpert Desk Reference as well as for a vari
4. in the directory that contains rngage exe 2 Torun the macro type amp r rngage exe at an ACT prompt and press Enter A menu will appear on the screen On the left side of the menu is a list of dates that have already been processed On the right side of the menu is a listing of USGS ASCII files that exist in the current directory Figure 17 Raingage and Rainfall Coverage Creation Menu Be careful in choosing an ASCII file from the righthand listing If you choose an ASCII file with a date that has already been processed the macro will delete the currently existing shapefiles and reprocess the data To proceed choose an ASCII file in the right listing and choose OK Or to cancel the operation choose Cancel You re now ready to run the Water Quality Water Quantity application with the new datasets Figure 9 Procedural Passage 4 for Review Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 31 1 Passive to Active Exercise Turn this tangled passive voice material to sparkling clear active voice procedures If you find any gaps in the process fill them in as well as you can Assume that the user is quite new to computers but knows basic mouse and Windows operations Also assume that the user might not know how to load a disk or CD but will know how to run and use Windows Explorer The process is begun with the startup disk that was includ
5. Handout The How To of How To s Writing Procedures Like a Pro STC 47th Annual Conference Orlando Florida May 22 2000 Handout The How To of How To s Writing Procedures Like a Pro STC 47th Annual Conference Orlando Florida May 22 2000 Prepared by Rebecca Edgerton Woolpert LLP 409 East Monument Avenue Dayton Ohio 45402 1261 Phone 937 341 9376 rebecca edgerton woolpert com Jill Nicholson J amp H Communications P O Box 79 Roseville Australia NSW 2069 jpnicho bigpond net au QUALITY At Woolpert LLP quality is the cornerstone of our business We invite your comments and suggestions for improving this document TRADEMARKS All brand names and product names are trademarks or registered trademarks of their respective companies NOTICE OF PROPRIETARY INFORMATION 2000 Woolpert LLP Dayton Ohio All rights reserved to Woolpert This document was designed prepared and submitted by Woolpert to be used only by the recipient None of this material is permitted to be reproduced in any way or distributed to anyone other than authorized representatives of the recipient TABLE OF CONTENTS The How To of How To s Writing Procedures Like a Pro 0 0 cece 1 Introduction Smin yeas cee douse an cee ad ee ae ele ad ae aaa ew dee lens 1 Why Procedural Writing Is Important 1 min 0 0 eect tenes 2 How a Process Description Differs from a Set of
6. Procedures 5 min 0000 ce eee 2 1 Process Description Exercise 10 min 0 cece eects 4 How to Identify Good Procedural Writing 5 min 20 0 eect eens 5 How to Write Good Procedures 5 min 1 1 0 eee e ett e eens 6 The Importance of Active Imperative Steps Telling Them Where to Go 5 min 9 The Importance of Parallelism Marching Two by Two 5 min 2 0 2000 9 1 Active Voice Parallelism Exercise 5 min 0 00 ccc ccc eee eens 11 The Importance of Sequencing Putting the Ducks ina Row 5 min 12 1 Step Sequence Exercise 5 min so soo oo i6dirst bdbsosideeediudeodicebivotiaes 14 A Questionnaire for Planning and Critiquing Procedures Staying on Track 15 1 Prose to Numbered Steps Exercise 5 min 0 cece ene e eee 18 Detailed Sequence Exercise 15 min n cannae p6aandsa dean nnwe candied 19 Additional Information 20 0 cece cnt ent eee e nee eae 20 Document Planning Pyramid The Relationship between Purpose and Type 20 Document Pumpose sed coiled ha aah ea OGG ae Fae AAG Se a O AS 20 Document Type sarira cicadas ocho need EGE E A ohdawdad E E aad 21 Audience Analysis acy ioe hod eden ebb eld be Goede dae eae dod eS eet 22 ASSUIMPUONS r eia Rios BEA And g aS 4 Rio a BENS iG Gating deg A aS Ro dG 6 cdg a Hess 23 Acknowledeoments 0s 5044s saad edee eo heeded die dae ead wa le des es 23 Sched
7. Street Address screen click Enter a List of Addresses 2 Then on the Multiple Address Entry screen shown in Figure 1 enter a house number street name and street type for each line of the screen You can enter up to 20 addresses 3 When you have finished entering the addresses click the Submit button After a few seconds the results of the entered addresses display as shown in Figure 2 The results are in groups An explanation of each group is above tine the group and a checkbox with an action is below the group Actions include these checkboxes Print this list prints a list of addresses that couldn t be p geocoded or prints a form describing each address s situation H Research these addresses adds that group s addresses to a database for county staff to research Results of Batch Process Following addresses roid not he keocoded H Print a report for these addresses prints a report for all a addresses that can be found by geocoding or by searching the databases 10125 STANDING STONE Finally click the box or boxes corresponding to each group and OF tata forthe subs click Submit addresses to perform those actions Figure 2 Batch Process Results Screen Figure 2 Example Set of Procedures Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 3 1 Process Description Exercise 10 min Wo
8. ________ Found in its apparent two minute location on the scanned search atlas sheet Skip to Step A10 C1 Knock at the door and spend a maximum of two minutes attempting to gain access A4 Is structure accessible D1 Pentop System i Digitize the structure on the pentop PC as i No Obscured in its apparent location on the scanned atlas sheet i Skip to Step A10 p A5 Is surveyors able to s structure _gain safe access to observable by s the structure r GPS A6 Observe the structure by GPS H C3 Pentop System Digitize the structure on i the pentop PC as Inaccessible Impeded in l its apparent location on the scanned atlas sheet Skip to Step A10 A7 Handheld Data Recorder Mark the structure as GPS on the office source map A8 Download the GPS data at the end of each day i i D2 Handheld Data B2 Handheld Data C4 Handheld Data i Recorder Develop Recorder Develop i Recorder Develop daily daily assignments to daily assignments to assignments to digitize the Inaccessible Impeded utility structures A9 Perform quality control digitize the Obscured digitize the Not Found on the GPS survey data utility structures i utility structures A A10 Run the datacheck macro on the ASCII file Figure 3 Example Flow Chart for a Very Complex Process Original Chart Is Color Coded
9. able 1 Our Criteria for Good Procedural Writing Criterion 1 11s tne fomnat comtoranie to use and appraprare oe aides He spe of use ana me tope 10 Is the writing clear and accurate 12 Is the level of detail appropriate to the task and the audience 20 Bottom line is the document usable If your job or your life depended on the success of the procedure could you do it Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 5 How to Write Good Procedures 5 min JoAnn Hackos of Comtech Services Inc recommends these techniques which we ve adapted for this presentation Table 2 Techniques for Good Procedural Writing Technique Put the steps in the order in which they should be done Use a modular design if the procedure is particularly long For a procedure that diverges and then links back again draw a flow chart If the procedure has aspects that can go wrong use these signs each formatted in a particular and identifiable way Rationale and Discussion This makes sense since you want the reader to do the steps in the right order This technique eliminates the dreaded do this after you do that problem which is where sequencing comes in We ll talk about that later A procedure with lots of steps can be daunting And how many that is depends on your audience the task and the setting in which the procedure
10. e In addition to any assumptions you ve made about the audience what do you assume about the project the data the participants the schedule e Do you consider a certain dataset as the authority or assume that a certain piece of software will be installed by a particular date e Are you relying on the accuracy of information given by a particular client employee department or committee Acknowledgments e What other documents resources can you consult e Acknowledge any significant material used directly or indirectly e Get written permission and keep the document e Don t rewrite what s already been written and is available from another source Schedule Budget and Production e What s the deadline e Does the deadline specify when must it be in the client s hands and when must it leave your office e Is it specified by the contract or by something else e What s the budget e For basic writing or rewriting allow at least one hour per page e For technical writing or rewriting allow at least two hours per page e For substantive editing allow at least 30 minutes per page e In planning for the deadline and the budget consider these things e The evils of documenting too early You may have to do the whole documentation job over again e The benefits of documenting too early The documentation can serve as an informal type of usability testing while the process or product is developed Woolpert STC 47th Annua
11. ed in the blue envelope marked Startup The disk medium should never be touched including the recording material under the metal slider The startup disk is inserted in drive A if the received medium is a 3 5 inch floppy or in the CD drive if the received medium is a CD which is configured as drive E and the door is closed with the green label facing up Install is typed and Enter is pressed in the Windows 95 Start Run box The project files BxxPyy are loaded onto the hard drive after a few minutes where xx is referenced to the book number and yy is referenced to the page number The new directory is called Sheets The 63 files should be verified to be on the hard drive after Installation complete is displayed on the screen and after Clear is clicked Windows Explorer should be used If any problems or questions are encountered the system administrator should be informed Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 32 Passive to Active Exercise A Solution 1 Find the blue envelope marked Startup It contains the startup disk Caution Ifyou received a 3 5 inch floppy disk never touch the recording medium under the metal slider If you received a CD handle it as little as possible and only by the very edge 2 Remove the startup disk from the envelope 3 Then use one of these steps e Ifyou received a floppy disk hold it with the g
12. ens 9 Figure 5 The More Technical the Purpose Left Side the More Structured the Form Right Side 20 Figure 6 Procedural Passage 1 for Review 0 cece cece eet ene ene e ene eeee 28 Figure 7 Procedural Passage 2 for Review 0 cece cece tent een eee tenes 29 Figure 8 Procedural Passage 3 for Review 0 c cece cece ene e nee ene 30 Figure 9 Procedural Passage 4 for Review 0 cece cect tet e nee ene eee 31 LIST OF TABLES Table 1 Our Criteria for Good Procedural Writing 0 ccc ccc eens 5 Table 2 Techniques for Good Procedural Writing 0 cece eee ene ene 6 Table 3 Our Rules of Sequencing 0 0 eee eet e ene e ene eens 12 Table 4 Process Description Versus Procedures 2 0 00 cece cece eect een eens 21 Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro ii THE How To oF How To s WRITING PROCEDURES LIKE A PRO By Rebecca Edgerton and Jill Nicholson Introduction 5 min As you re getting settled please find a partner nearby You ll need a partner for some of the exercises we ll do Consider these two passages Press F12 Unless you don t want to delete everything you have entered Determine the number of hours of sick leave which may be credited to an employee other than a part time employee by multiplying the total months of service of the s
13. ent Word 1 To change a replacement word select the word in the list and then choose Edit 2 Type the new word and choose OK 3 Then choose Close Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 27 Additional Exercises 1 The Good the Bad and the Ugly Exercise Select at least one of the following passages to review Evaluate the passage using the criteria listed in the table called Our Criteria for Good Procedural Writing Be prepared to discuss your evaluation Woolpert May 22 2000 This passage is from the map sheet work procedures section of a document called Procedures and Quality Control for Planimetric Mapping Task 2 Perform Analytic Triangulation Task Overview Horizontal and vertical control points that are marked in the field will be identified on contact prints Pass points and tie points will be marked on diapositives Diapositives will be drilled with a point transfer device On a stereoplotter the operator will measure the pass points and tie points on each photo Fully analytic triangulation calculations will be performed Before aerial photography is obtained experienced field crews will place markers on existing or supplementary horizontal and vertical control These markers must be large enough to be seen on the aerial photography and must be adequately pinned to the ground so that they will remain in place until the aerial pho
14. er who may not actually be reading the step numbers Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 12 Table 3 Our Rules of Sequencing Rule Notes and Exceptions Use a special convention for When a step contains an or loop use this type of convention or loops starting with the most common default action and setting off the Or for emphasis 7 Then use one of these steps e Ifyou received a floppy disk insert it into the floppy drive drive A e Or if you received a CD insert it into the CD drive drive E Use loops as necessary Minimize the number of loops Always loop to something recognizable like a step number Support the step text with a flow chart that uses the same step numbers For one or more optional steps consider using a box to separate them from the rest of the process Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 13 1 Step Sequence Exercise 5 min Work with your table for this exercise You have five minutes Change the order of the steps in this procedure to make it sequential The procedure is for finding and replacing formatting in Word thanks to Running Microsoft Word 97 from Microsoft Press for the inspiration for these steps First choose the Edit Replace command Click Format to open the format list Click Format to open the for
15. ercise A Solution 3 min Here s one way To compute the number of sick days credited to a full time employee use these steps 1 First count the total number of months of service 2 Multiply by 4 3 Subtract the number of sick leave hours already taken Here s a shorter way Sick leave for full time employees months of service x 4 hours already taken e What kind of audience would respond better to the first way e What kind of audience would respond better to the second way Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 26 Detailed Sequence Exercise A Solution 5 min Specifying Replacement Words 1 Open the Dictionaries menu and choose Replacements Or open the Dictionaries menu choose Select Dictionaries and then choose Replacements 2 Choose Add 3 Type the incorrect word in the Change box 4 Then type the correct work in the To box 5 Ifyou would like this word to be automatically substituted in every document select AutoReplace During Grammar Check Or you might want to add a comment in the Advice box explaining when to use the replacement 6 Choose OK 7 When you have completed your replacements list choose Close Optional Deleting a Replacement Word 1 To delete a replacement word select the word in the list and then choose Delete 2 To confirm the deletion choose Yes Optional Changing a Replacem
16. ety of hardware and software users manuals procedure guides and technical implementation plans Jill Nicholson is an experienced technical and business communicator who lectured on science and technical communication skills for many years at the University of Technology Sydney Australia She now presents business and technical communication courses to government departments and the private sector in Australia New Zealand and Singapore as well as providing technical writing services Since leaving the university in 1995 Jill has worked for herself and has contracted teaching and technical writing services to a number of major companies Since 1994 she has also organized the annual JoAnn Hackos Seminars presented in Australia Jill is a senior member of STC and has served as President of the Australian Society for Technical Communication NWS Inc Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 35
17. he process supporting information is often research done and related topics omitted or in an appendix e Can be formal or informal even chatty e Is usually very structured but not necessarily reflecting the personality of the writer formal and is usually not chatty reflecting little of the personality of the writer Often has illustrations and tables Often has screens color coding icons and special typographic conventions such as bold for menu items italics for database field names e May follow a variety of standards including May follow a standard such as The Microsoft in house standards industry standards and Manual of Style for Technical Publications various style guides e Is used for a report or a general plan e Is used for a procedures manual or a detailed plan Audience Analysis e Whom are you writing for e Don t know nobody showstopper e Many people everybody showstopper e What must the reader know and how necessary is that knowledge e Basic computer skills mouse keyboard are required e Particular software skills are desirable e Specialized organizational knowledge is helpful e What does the reader expect from the document e Do the reader s expectations follow the contract specs e Do the reader s expectations follow some verbal specs Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 22 Assumptions
18. itfeatures Use the mouse to select the editfeature The FEATURE field on the DATA SETS portion of the KWIK user interface displays the editfeature you select STRUCTURE The screen displays a popup scrolling list of structures Use the mouse to select the structure The STRUCTURE field on the DATA SETS portion of the KWIK user interface displays the structure you select SETTINGS Use this button to display a customized Edit Settings menu to edit various settings see Figure 3 below SELECTS Use this button to display a pulldown menu to choose between various feature selecting options EDITS Use this button to display a pulldown menu of commonly used AtekEase edit function commands MISCELLANEOUS Use this button to display a pulldown menu of informational AtekEase commands DISMISS Use this button to exit from the AtekEase menu and return to the Banner menu see Figure earlier in this section Figure 7 Procedural Passage 2 for Review Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 29 This passage is an excerpt from a user manual Step 11 Choosing a Service After you select Service in Step 10 the County Services Menu displays ile Edit Layout Graphics Window Help Taal agp y ae EFEKRKI County Services Choose a se
19. l Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 23 The Rest of the Story Here are the answers to the exercises in the main part of this document Active Voice Parallelism Exercise A Solution 3 min Part A Here are three different versions of the list showing parallel construction 1 2 Run the software 1 Running the software 1 Torun the software Select the file 2 Selecting the file 2 To select the file Digitize the feature 3 Digitizing the feature 3 To digitize the feature Plot the file 4 Plotting the file 4 To plot the file Review the plot 5 Reviewing the plot 5 To review the plot A You might wonder why there were only three examples of parallel lists and no example showing the noun of construction used in Review of the plot The reason is that the noun of construction tends to be heavy whether it occurs in a list a heading or text In all those cases it s better to say Review the plot than to say Review of the plot This is even more important with bigger words and longer phrases as in I will perform the estimation of the costs which is much improved when revised to P1 estimate the costs Part B Here are the corrected versions of the sentences Opening and closing files are easy to do 2 Identify the type of disk and the way to handle it 3 The error is due either to a lack of disk space or to a power inter
20. le If you are sending a notice to a borrower why are you sending it You might send a notice to tell the borrower that his or her loan has been approved If you are completing a form why are you filling it out You might fill out an adjusting entry request form to ask that the accounting department review the entry 2 What causes you to begin the procedure Example A call from a borrower causes you to fill out a request form asking that a letter be sent to the borrower 3 How do you know when you re finished Example When getting information from a file you re finished when you find the information When filling out a form you re finished when the form is complete 4 What do you do with the information after you ve completed the procedure Example After you complete a request form you send it to the information services department 5 What steps do you follow to complete this procedure It is important that you describe all the steps as thoroughly and carefully as possible Describe the steps as if you were explaining them to a person just hired to perform the procedure Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 15 Don t leave out the steps that are performed by people in other departments or by the computer even if you don t know the details of what they do Number all the steps that way you can refer back to them by nu
21. lete STC 47th Annual Conference Woolpert May 22 2000 The How To of How To s Writing Procedures Like a Pro 6 Table 2 Techniques for Good Procedural Writing Technique Rationale and Discussion Write short explicit They re much easier for the reader to follow Sentences that are overly sentences long can signal one of two conditions An if then or even if then else structure which would be better handled as a set of parallel bullets e A step that actually contains multiple actions which would be better handled in separate steps Use commanc style That s the imperative If you use you should or you might the reader sentences that begin with may think there is an alternative to what you re describing Even worse if a verb such as do this you use passive voice will be copied or will be opened the reader and open that may not be able to tell what to do and what happens automatically Using imperative verbs can also help prevent problems with nonparallel construction We ll get to that in a bit too Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 7 A1 Develop daily assignments for GPS crews A2 Begin the primary sweep GPS survey to locate utility structures B1 Pentop System Digitize the structure on utility structure the pentop PC as Not be found within a No _
22. mat list To display the whole Find and Replace dialog box click the More button Delete any text from the Find What box Woolpert With the format list open select the type of formatting you want to use as a replacement You can select as many different types of formatting as you need Click Find Next to decide about the first replacement To continue finding click Replace or click Find Next again Or click Replace All at any time to replace all instances In each formatting dialog box select the formatting you want to find and click OK With the format list open select the type of formatting you want to replace You can select as many different types of formatting as you need Delete any text from the Replace With box In each formatting dialog box select the formatting you want to use as a replacement and click OK STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 14 A Questionnaire for Planning and Critiquing Procedures Staying on Track If you have trouble working out the sequence of a procedure the parts of the procedure that are important or the parts of the procedure that may need to be divided into smaller parts try asking these questions This information is adapted from Designing Effective Standards and Procedures a course presented by JoAnn Hackos 1994 JoAnn Hackos and Associates Inc 1 Why do you perform this procedure Examp
23. mber EA It will probably take you some time to do this You might want to write each step on a separate page before you write the final version 6 Look at all the steps you have just written down Some may be more complicated than others For example you may have to calculate an account balance or identify a trend In detail how do you do that Example If you calculate an account balance explain all the steps Where do the numbers come from How do you make the calculation Do you check your work oa You don t need to answer this question if you ve A described all the steps thoroughly in Question 5 Look over the steps once more Note any steps where you must make a decision Explain how you make the decision for each step Example Ifyou must decide whether to approve a request explain under what conditions you would approve it and under what conditions you would deny it 7 How much time does it ordinarily take you to perform the entire procedure Estimate as carefully as possible the amount of time you take to complete this procedure and its steps If applicable give a range of possible times for example between 15 and 30 minutes and explain the reasons for the extremes You might explain that you can complete a procedure in 15 minutes if the information is available on the computer but that it takes you 30 minutes if you have to consult a file EA What we re looking for is the time you spend on the pr
24. nk of an even shorter way to convey that information Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 18 1 Detailed Sequence Exercise 15 min Work with your table for this exercise You have 15 minutes In the following procedures find sequence errors like multiple actions in one step the dreaded do this after you do that and so on Also think about how many tasks or modules this list includes Thanks to the WordPerfect User s Guide from Novell Inc for these procedures which we ve mutilated Specifying Replacement Words 1 Choose Replacements after opening the Dictionaries menu 2 Or open the Dictionaries menu choose Select Dictionaries and then choose Replacements 3 Choose Add type the incorrect word in the Change box and then type the correct work in the To box 4 Ifyou would like this word to be automatically substituted in every document select AutoReplace during grammar check Or you might want to add a comment in the Advice box explaining when to use the replacement 5 Choose OK 6 Choose Close when you have completed your replacements list 9 To delete a replacement word choose Delete after you select the word in the list 10 Choose Yes to confirm the deletion 10 To change a replacement word select the word in the list Then choose Edit 11 Type the new word 12 Choose OK 13 Then choose Close Woolpert STC 47
25. ocedure If you have to wait for information from someone else don t include that time Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 16 10 Some of the steps you perform may take a lot more time than others What are those steps and about how long does it take to perform them Example Out of the 30 minutes it takes you to fill out a form you might spend 20 minutes calculating one number What can go wrong when you perform the procedure Example Maybe you or someone else entered the wrong social security number What do you have to do to correct the mistake If other people are involved explain as much as you can about what they do Example To correcta social security number you might go back to the borrower s file and check the original promissory note Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 17 1 Prose to Numbered Steps Exercise 5 min Work with your table for this exercise You have five minutes Convert the following paragraph to structured text with numbered steps The number of hours of sick leave which may be credited to an employee other than a part time employee shall be determined by multiplying the total months of service by four and subtracting therefrom the sum total of the number of hours of sick leave previously taken Then can you thi
26. ould be parallel They can Figure 4 Example Procedure Dialog all begin e With ing words Creating a File Deleting a File e With imperatives Create a File Delete a File e With nouns Creation of a File Deletion of a File e With infinitives To Create a File To Delete a File EA What important advantage do the first three methods have A over the fourth method e Parallelism is important within sentences within headings and in lists Bad Taking all the parts out of the box and check them with the parts list to make sure you received everything Good Take all the parts out of the box and check them with the parts list to make sure you received everything e Parallelism is especially important in phrases with and or 13 29 or Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 9 Bad Open inspect and assembling the toy Good Open inspect and assemble the toy e Bad Either they work or are fired Good Either they work or they are fired Bad Whether at home or working he was always busy Good Whether at home or at work he was always busy Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 10 1 Active Voice Parallelism Exercise 5 min Work on your own for this exercise You have five minu
27. reen label facing up and insert it into drive A e Or if you received a CD hold it with the green label facing up and insert it into the CD drive 4 Close the drive door 5 On the Windows 95 taskbar click Start and then Run 6 Then use one of these steps Fora floppy disk make sure the box says A install and click OK e Or for a CD make sure the box says E install and click OK 7 Wait while the installation proceeds The process automatically creates a directory called Sheets on your hard drive and loads the project files When the process is done Installation complete displays on the screen 8 Click Clear 9 Use Windows Explorer to make sure that the Sheets directory on your hard drive contains 63 project files Note The project file names use the pattern BxxPyy where e xx is the book number e yy is the page number For Help If you have any problems or questions contact the system administrator at Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 33 Selected Bibliography Alred Gerald Charles Brusaw and Walter Oliu The Professional Writer A Guide for Advanced Technical Writing New York St Martin s 1992 Anderson Paul Technical Writing A Reader Centered Approach 3rd ed New York Harcourt Brace Jovanovich 1995 Borland Russell Running Microsoft Word 97 Redmond WA Microsoft 1997 Cormier Robin Error Free Writing
28. rk with your partner for this exercise You have 10 minutes Write a paragraph or two to describe one of the following processes An example process is done for you so don t choose that topic Remember not to write procedures and focus on telling what rather than how Process Example Reconciling a Checking Account Reconciling a checking account begins with assembling the materials such as the most recent bank statement the check register the latest batch of canceled checks and a calculator Before beginning the reconciliation the account holder enters any outstanding transactions into the check register Then he or she compares the recent deposits canceled checks and other transactions from the statement with the check register Next the account holder adds up outstanding transactions and adds or subtracts them to the statement balance as appropriate As a result the adjusted statement balance should match the register balance If the two balances don t match the account holder should review the process to identify the error Process 1 Changing a Tire Process 2 Heating a Can of Soup Process 3 Mowing the Lawn Process 4 Washing Dishes Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 4 How to Identify Good Procedural Writing 5 min How many of these characteristics apply to the short procedural example we looked at a few minutes ago T
29. rt STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 20 e No purpose showstopper e Too many purposes showstopper e Can you identify the real reason as opposed to the contract reason But what does the contract say about it Document Type e What type of document do you intend to or need to write e The level of structure ranges from freeform to structured technical e The type of document ranges from memo to online help e What venue e Hardcopy online or both e Can it really be both Here s a table that summarizes the differences between a process description and procedural writing Table 4 Process Description Versus Procedures A Process Description Procedural Writing Is a description that tells what rather e Is a set of instructions that tells how rather than how than what Documents what someone did or will do Tells exactly how to get from point A to point B without telling exactly how may also persuade assumes that no persuasion is necessary e Assumes that the reader may not be the e Assumes that the reader probably will be the person to carry out the process person to carry out the process Assumes that the reader will read the entire e Assumes that the reader will read only the parts document or at least major chunks of it maybe just the single item needed e Usually has a third person he she the user
30. ruption 4 The application begins by opening the file displaying the list and calculating the total 5 Use F7 to generate a new chart but not fo edit an existing one Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 24 Step Sequence Exercise A Solution 3 min 1 First choose the Edit Replace command 4 Click Format to open the format list 8 Click Format to open the format list 2 To display the whole Find and Replace dialog box click the More button 3 Delete any text from the Find What box 9 With the format list open select the type of formatting you want to use as a replacement You can select as many different types of formatting as you need 11 Click Find Next to decide about the first replacement 12 To continue finding click Replace or click Find Next again Or click Replace All at any time to replace all instances 6 In each formatting dialog box select the formatting you want to find and click OK 5 With the format list open select the type of formatting you want to find You can select as many different types of formatting as you need 7 Delete any text from the Replace With box 10 In each formatting dialog box select the formatting you want to use as a replacement and click OK Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 25 Prose to Numbered Steps Ex
31. rvice you want information about Clermont County GIS Available Services Absentee Ballots Adoption Adult Protective Services Agricultural Services Aid to Dependent Children ADC Animal Disposal Figure 11 The County Services Menu The dialog box displays a list of county services This is a special kind of list a scrolling list The scroll bar the vertical gray bar at the right of the list indicates that only part of the list fits in the box Move the mouse pointer through the list to find the service you want more information on To move down quickly in the list click in the gray vertical scroll bar area above the button When you find the service you want select it Then click OK and continue with Step 12 Figure 8 Procedural Passage 3 for Review Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 30 This passage is from an application user guide Configuring Updated Data for the Water Quality Water Quantity Application Overview Rainfall data is available for certain dates on the U S Geological Survey USGS web site The data exists as simple ASCII files that must be processed before being used by the Water Quality Water Quantity application XYZ has written a set of macros to automate the conversion of the ASCII textfiles into a format suitable for GIS Here is how to run the macros 1 Start
32. s will be used In some cases five steps could be too many in others 20 could be fine Even with step numbers readers can have a hard time keeping their place So use chunking or modules to separate the procedure into unified components You may find down the line that you need to refer back to a single component anyway This is one of those times when it s much better to show and tell than just to tell Be sure the flow chart and the text use the same step numbers and titles See the next figure for an example of a very complex flowchart You are responsible for effectively notifying the reader about these circumstances In some cases your level of responsibility could amount to legal liability And remember that the formatting of these signs is part of the recognition signal for the reader So special icons color or other formatting can be useful DANGER for steps that may lead to personal injury or death Some common icons to use are and 2 often quite large and in red WARNING for steps that could result in damage to equipment Caution for steps where incorrect results or a loss of time could occur Note for alerts to possible problems The icon we used in this document is EN although many writers use just the word Note in a prominent font and size Write using the Nothing is more annoying than a step the reader can t understand So vocabulary of your reader don t say expunge when you mean de
33. tes Part A From this mixed up list create a set of active imperative items in parallel structure l 2 3 4 3 Run the software The file should be selected Digitizing the feature To plot the file Review of the plot Part B Fix the faulty parallelism in these sentences 1 Opening and to close files are easy to do Identify the type of disk and how disks should be handled The error is due either to a lack of disk space or a power interruption The application begins by opening the file displaying the list and then calculates the total Use F7 to generate a new chart but not for editing an existing one The appendix at the end of this handout includes a more detailed passive to active exercise Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 11 The Importance of Sequencing Putting the Ducks in a Row 5 min What s wrong with this instruction Press Escape to delete everything you have entered and cancel the operation It breaks one of the basic rules of sequencing It s an example of the dreaded do this if you want to do that This table lists the basic tules for sequencing Table 3 Our Rules of Sequencing Rule Notes and Exceptions Put all steps in e In a document like a reference manual options might be in chronological order alphabetical order or in the order they re listed on a computer screen rather
34. th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 19 Additional Information Document Planning Pyramid The Relationship between Purpose and Type To Letter inquire memo To Letter memo convince proposal To document Report scope a process of services To build Tutorial skills online training To tell how to Procedures perform a process manual user guide To answer questions Reference guide about a process online help system To troubleshoot Reference guide online or repair help system repair manual Document Purpose Document Type Figure 5 The More Technical the Purpose Left Side the More Structured the Form Right Side In the figure Document Purpose on the left gets increasingly technical from top to bottom and Document Type on the right gets increasingly structured from top to bottom The document purposes and types shown in are the most likely candidates for procedural writing Document Purpose e Why are you writing e What need should the document fulfill e What problem should it prevent or solve e You and the recipient user client must agree The more you know about the purpose the more focused the document will be Don t start writing until you can express the purpose for the document in one to four sentences Don t start writing until you can express the purpose for each chapter section and page in one sentence Woolpe
35. than in chronological order Number every step e Use numbers for steps but use bullets or letters for options or components within a step Put information within each e As above it may be advisable to list options or other items in step in chronological order alphabetical or some other order Avoid the dreaded do this if This construction is illogical like a then if in programming you want to do that Structure the step like this To do this do that Avoid the dreaded do this e This construction is also illogical Structure the step like this First after you do that do this and then do that Use one action per step Tack the instruction to press Enter or select OK onto the end of a step Combine closely related actions in one step Click in this box and type that Make sure every numbered step contains at least one action for every reader So an optional step shouldn t have its own number See Or loops below Watch the number of steps Make sure the number of steps fits the task and the reader Will the reader be comfortable with a 50 step process or would it be better to separate the steps into individually numbered modules If you re writing instructions on how to install a hearing aid battery would 25 steps be too many Use transitions to build Transitions might seem unnecessary since the steps are connections between steps numbered But transitions help orient the read
36. tography has been completed After the aerial photography is obtained the contact prints will be carefully inspected to ensure that all premarked control is properly visible and identifiable on the aerial photography If critical points cannot be seen clearly on the photography or if a premark has been removed it will be necessary to return to the field to tie in a nearby natural photo identifiable point Figure 6 Procedural Passage 1 for Review STC 47th Annual Conference The How To of How To s Writing Procedures Like a Pro 28 This passage is from a user manual AtekEdit Menu Access the AtekEase menu by selecting AE MENU on the Banner menu shown previously in Figure 1 Use the AtekEase menu shown in Figure 2 to execute a variety of common AtekEase tasks SS Figure 2 AtekEase Menu DEVICES Use this button to display a pulldown menu that includes standard AtekEase commands and AMLs for setting up a drawing and activating the digitizer mouse and keyboard DATA Use this button to set the editcoverage editfeature and structure The screen displays a pulldown menu with three choices e EDITCOVERAGE The screen displays a popup scrolling list of available editcoverages for the current production area Use the mouse to select the editcoverage The COVERAGE field on the DATA SETS portion of the KWIK user interface displays the editcoverage you select EDITFEATURE The screen displays a popup scrolling list of ed
37. ubject employee by four and subtracting therefrom the sum total of the number of hours of sick leave previously taken by the subject employee This workshop will cover these topics e The difference between a process description and procedures e The characteristics of good procedural writing e The mechanics of procedural writing like active voice parallelism and sequencing Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 1 Why Procedural Writing Is Important 1 min Activities other than typical procedures documents that good procedural writing can help e Telling someone how to drive to your office e Writing a scope of services for a contract How a Process Description Differs from a Set of Procedures 5 min Here are two examples using the same topic Entering Multiple Addresses With this application the user can submit up to 20 addresses The software geocodes as many addresses as it can and then identifies any addresses that can t be geocoded The user can print a list of the addresses that weren t geocoded print a form that describes each address s situation identify addresses for researching or print a report on the addresses Figure 1 Example Process Description Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro 2 Entering Multiple Addresses 1 On the
38. ule Budget and Production 0 23 ThE RESt OF the Story jwsnduwei ease deen sa bideranetee ge eased basen n E 24 Active Voice Parallelism Exercise A Solution 3 min 00 0 e eee 24 Step Sequence Exercise A Solution 3 min 2 00 eee eee eee eee 25 Prose to Numbered Steps Exercise A Solution 3 min 00 0 0 eee eee 26 Detailed Sequence Exercise A Solution 5 min 0 0 cece eee eee 27 Additional Exercises 2 0 ccc cent e nent e nent en en eeto 28 1 The Good the Bad and the Ugly Exercise 2 7204 001 4eica cs decuey cet be leave ens 28 1 Passive to Active Exercise oo 0h 4 cvaaie n dhe Gaas needa Renaud Ga vkan eae paarnded 32 Passive to Active Exercise A Solution 2 0 0 0 cece eee eee ees 33 Selected Bibliography 0 0 0 0 ccc ee eee eet een nea 34 Acknowledgment g 06 sas0s ead need nea phe hae eae aR aa Sa alee aa Sea 34 About the Presenters 00 0 e eee bene e ne en en enes 35 Woolpert STC 47th Annual Conference May 22 2000 The How To of How To s Writing Procedures Like a Pro i LIST OF FIGURES Figure 1 Example Process Description 0 cece cee ent n ence eens 2 Figure 2 Example Set of Procedures 2 0 0c cece e eee ene een en eeae 3 Figure 3 Example Flow Chart for a Very Complex Process Original Chart Is Color Coded 8 Figure 4 Example Procedure Dialog 1 0 2 0 cece een tent een e
Download Pdf Manuals
Related Search