writing a step-by-step guide to a task one does every day is difficult. imagine i’ve just asked you to write down how you make a pot of coffee: you scoop, pour some water, press the button. you don’t even think about it, right? now imagine that i’ve never made a pot of coffee and don’t know where to put the scooped grounds, or how much water to use. it’s important for you to tell me explicitly. this is the approach i take when i direct somebody to write a procedural document: imagine that i’ve seen a coffee pot, but never actually used one. perhaps i’ve had a monkey butler bring me my coffee all my life but i’ve now fallen on hard times and must learn to make it myself. i need your help.
start your document with a one or two sentence introduction of the task you’re going to describe. be sure to note which computer software is used to perform the task, if any. if there’s anything you want your reader to consider while they’re performing the task, include it in the introduction, before you launch into the steps. commit to using no acronyms or jargon throughout the document.
in an ordered list, write each step of the task on its own line, in its own number. consider that each step should be small. if you find yourself writing more than a sentence or two per step, you’re probably describing two separate steps.
the last step of a document should be a summary of the completed action. for example, you may say, “once you’ve pushed the brew button twice, the machine will start to brew the coffee and will be ready in about five minutes.”
i’ve reviewed documentation over the years and have not been able to discern the provenance of the file, which can be important if there are two documents in a folder with similar file names: how does one distinguish which is the current document? by inserting date information into a footer or header of the document, the metadata travels with the document. note in the footer the author and on what date the document was written (include year) and what the path is if the document is stored on a shared drive. include the document name in the path.
example: written by Marie Kennedy 2/26/2009. G:\Acquisitions\Documentation\make_coffee.doc
if that document is reviewed or revised, keep a copy of the original in an archive folder. G:\Acquisitions\Documentation\Archive\make coffee.doc. on the new document, include the review [no changes made] or revision date in the footer.
example: written by Marie Kennedy 2/26/2009, reviewed 2/27/2010. G:\Acquisitions\Documentation\make_coffee.doc
finally, here is a small example of how a document can be written:
This procedure describes the steps for making coffee in the Braun coffee maker in the Acquisitions office. The coffee drinkers in the office prefer spring water to tap, so use the bottle of water underneath the sink to make the coffee. Extra cups are next to the water bottle.
- Open the filter holder and place a #2 coffee filter into the filter holder.
- Using the measuring spoon next to the coffee pot, scoop out one spoonful of coffee per cup. If you’re making 8 cups, scoop 8 spoonsful of coffee.
- Close the filter holder. It will snap shut.
- Fill the carafe with water to the line on the carafe of the number of cups you’re making. If you’re making 8 cups of coffee, fill the carafe with water to the line marked 8.
- Open the water storage tank and pour the water from the carafe into the tank. Pour slowly and carefully, as the storage tank is in an odd place and will overflow if you pour too quickly.
- Place the carafe under the filter holder.
- Turn the on/off switch to on. The machine will automatically begin to brew the coffee and will complete in about 5 minutes.
