際際滷

際際滷Share a Scribd company logo

Features of a well written procedure

A
Andre Mars

The document provides tips for writing well-written procedures. It recommends that procedures should be short, clear, use the active voice, have a title identifying the task, identify any prerequisites, and follow a logical sequence of steps with one action per step. Graphics should be used appropriately, and procedures should have a conclusion and avoid annoying the reader.

1 of 3
Download to read offline
What makes a well-written procedure? By Thomas Quine Thomas Quine teaches the fundamentals of technical writing at the University of British Columbia, and is the principal of Documen Information Design, Inc. (www.documen.com). Procedure writing is at the heart of technical writing. People sometimes read technical publications for detailed specifications, for product descriptions, or for other nuggets of information, but most commonly people read manuals for one reason alone to answer the question, How do I do what I have to do? A well-written procedure answers that question. Two years ago I polled technical writers about what they considered to be the essential features of a well-written procedure. Since that time I've taught what Ive learned about writing procedures to dozens of technical writers, and received a lot of valuable feedback. Heres a few tips that working writers in the field tell me will contribute to the creation of a well-written, easy-to-follow procedure: Use the Title to Define the Task Procedures are supposed to tell you how to perform a task or series of tasks. Unless these are clearly defined up front, your readers may not be motivated to complete the steps. The task at hand can be defined in an introductory paragraph, such as Follow the steps below to change the brake fluid in your car. But usually its shorter and clearer just to state the task in the procedure title. How to change the brake fluid in your car. Identify Prerequisites There are two types of prerequisites to the correct performance of a procedure: physical prerequisites (e.g. an Allen key, a flat-blade screwdriver, etc.), and prerequisite knowledge (e.g. Customer numbers must be numeric and not longer than 8 digits.) Prerequisites, especially physical prerequisites, can be identified in an introductory paragraph. A checkoff list can be a useful format for these. However, its often more effective to place prerequisite knowledge as close as possible to the actual performance of an action, if not immediately before, then immediately after. Only add prerequisite knowledge if it is a show-stopper; that is, if not knowing this vital piece of information means that a significant percentage of your readers will not be able to perform the procedure without it. Keep it Short Remember that your readers are people in a hurry. They have a job to get done, right away. Early studies by Bell Telephone showed that people have enough short-term memory to handle telephone numbers of up to seven digits, but that retention drops off with eight or more. (With the increasing use of 10-digit numbers in North America, many of us are learning this first hand) For this reason, many technical writers keep to the seven plus or minus two rule when determining how many steps should go into a written procedure. Of course, its not always possible to fit a complex procedure into five or seven steps, and a good writer will never sacrifice clarity in favour of an arbitrary rule but keep in mind that the longer the procedure, the more your readers attention will wander. Where possible, break down a long procedure into two or more shorter procedures.
Make it Clear Use simple language and short sentences. Avoid idioms that may not translate well. Never introduce a new technical term or jargon without explaining it first. Base any assumptions you have about your readership on careful audience analysis. Be concise! Use the Active Voice Address the reader directly. Use the imperative. Dont be shy about telling your reader what to do thats why theyre reading! One of the telltale features of the passive voice is that its hard to tell who the actor is. Heres a real- life example from a manual I recently read: The OK button must be clicked before returning to the Customer Address page. Instead of leaving the reader to guess who should be doing the clicking, why not engage the reader and address them directly: Click the OK button to return to the Customer Address page. Number the Steps By definition, a procedure is a series of actions meant to be performed in sequence. This implies that the successful completion of later steps may rely on earlier steps. If there were only a few non-sequential steps in the procedure, it might be possible to use bullets instead of numbers. Even so, numbers help the reader determine where they are on the page. Describe One Action per step Your readers attention is often shifting between reading a step and performing it. If you try to put in more than one action per step, you will lose a percentage of your readers. Therefore, wherever possible, break up a compound step into two separate steps. For example, if one of your steps reads Enter the Customer Number in the Customer Number field and click the New button, you can be sure that many readers will enter the number and move straight to the next step, missing the part about the New button. Use parallel structure The grammatical elements in every step in your procedure should match. For example: 1. Fly to Montana 2. Drive to North Dakota 3. Topographical maps 4. Hike through the badlands. Remember the Sesame Street song, One of these things is not like the others?
Use graphics appropriately A picture tells a thousand words! But a picture that is just used for decoration and does not explicitly support the information in the text will only distract or irritate the reader. Write a conclusion Ive learned through direct observation during usability testing that readers love a concluding sentence that signals to them that they have successfully completed the procedure. Congratulations! Youve just changed the oil in your car! Without a conclusion, theyll turn over the page and ask Is that it? Dont Annoy the Reader! Sounds obvious, but this is cardinal rule of technical writing is broken every day. Typically, when people cant figure out how to do something, their first impulse is to ask a colleague. Their next thought is to telephone someone who might know better than they do perhaps another colleague, or a technical support rep. If they cant find anyone to talk to, as a last resort theyll read something on their own. But keep in mind that before they even pick up your manual, theyre already annoyed that something isnt working as it should, and that no one is there to tell them how to do it right! If at this point you present the reader with something annoying, you run the risk of them throwing up their hands in despair and cursing the documentation forever. The writing in procedures should be transparent. That means that the reader should see right through the writing to the information behind it, just as you look through a picture window to see what the weather is like. If you notice the window, perhaps thats because it has grime and smudges all over it! Some of the greasy fingerprints that annoy readers are poor spelling, typos, sexist or racist language, jargon, clich辿s and idioms, flowery or literary style, digression, poor attempts at humour and even misconceived metaphors When in doubt strike it out! Summary Remember, a well-written procedure: Is short Is clear Uses the active voice Has a title Identifies prerequisites Clearly defines the task Accurately defines the outcome Follows a logical and sequential progression Describes one action per step Uses parallelism Uses graphics appropriately Has a conclusion Does nothing to annoy the reader!

More Related Content

Features of a well written procedure

  • 1. What makes a well-written procedure? By Thomas Quine Thomas Quine teaches the fundamentals of technical writing at the University of British Columbia, and is the principal of Documen Information Design, Inc. (www.documen.com). Procedure writing is at the heart of technical writing. People sometimes read technical publications for detailed specifications, for product descriptions, or for other nuggets of information, but most commonly people read manuals for one reason alone to answer the question, How do I do what I have to do? A well-written procedure answers that question. Two years ago I polled technical writers about what they considered to be the essential features of a well-written procedure. Since that time I've taught what Ive learned about writing procedures to dozens of technical writers, and received a lot of valuable feedback. Heres a few tips that working writers in the field tell me will contribute to the creation of a well-written, easy-to-follow procedure: Use the Title to Define the Task Procedures are supposed to tell you how to perform a task or series of tasks. Unless these are clearly defined up front, your readers may not be motivated to complete the steps. The task at hand can be defined in an introductory paragraph, such as Follow the steps below to change the brake fluid in your car. But usually its shorter and clearer just to state the task in the procedure title. How to change the brake fluid in your car. Identify Prerequisites There are two types of prerequisites to the correct performance of a procedure: physical prerequisites (e.g. an Allen key, a flat-blade screwdriver, etc.), and prerequisite knowledge (e.g. Customer numbers must be numeric and not longer than 8 digits.) Prerequisites, especially physical prerequisites, can be identified in an introductory paragraph. A checkoff list can be a useful format for these. However, its often more effective to place prerequisite knowledge as close as possible to the actual performance of an action, if not immediately before, then immediately after. Only add prerequisite knowledge if it is a show-stopper; that is, if not knowing this vital piece of information means that a significant percentage of your readers will not be able to perform the procedure without it. Keep it Short Remember that your readers are people in a hurry. They have a job to get done, right away. Early studies by Bell Telephone showed that people have enough short-term memory to handle telephone numbers of up to seven digits, but that retention drops off with eight or more. (With the increasing use of 10-digit numbers in North America, many of us are learning this first hand) For this reason, many technical writers keep to the seven plus or minus two rule when determining how many steps should go into a written procedure. Of course, its not always possible to fit a complex procedure into five or seven steps, and a good writer will never sacrifice clarity in favour of an arbitrary rule but keep in mind that the longer the procedure, the more your readers attention will wander. Where possible, break down a long procedure into two or more shorter procedures.
  • 2. Make it Clear Use simple language and short sentences. Avoid idioms that may not translate well. Never introduce a new technical term or jargon without explaining it first. Base any assumptions you have about your readership on careful audience analysis. Be concise! Use the Active Voice Address the reader directly. Use the imperative. Dont be shy about telling your reader what to do thats why theyre reading! One of the telltale features of the passive voice is that its hard to tell who the actor is. Heres a real- life example from a manual I recently read: The OK button must be clicked before returning to the Customer Address page. Instead of leaving the reader to guess who should be doing the clicking, why not engage the reader and address them directly: Click the OK button to return to the Customer Address page. Number the Steps By definition, a procedure is a series of actions meant to be performed in sequence. This implies that the successful completion of later steps may rely on earlier steps. If there were only a few non-sequential steps in the procedure, it might be possible to use bullets instead of numbers. Even so, numbers help the reader determine where they are on the page. Describe One Action per step Your readers attention is often shifting between reading a step and performing it. If you try to put in more than one action per step, you will lose a percentage of your readers. Therefore, wherever possible, break up a compound step into two separate steps. For example, if one of your steps reads Enter the Customer Number in the Customer Number field and click the New button, you can be sure that many readers will enter the number and move straight to the next step, missing the part about the New button. Use parallel structure The grammatical elements in every step in your procedure should match. For example: 1. Fly to Montana 2. Drive to North Dakota 3. Topographical maps 4. Hike through the badlands. Remember the Sesame Street song, One of these things is not like the others?
  • 3. Use graphics appropriately A picture tells a thousand words! But a picture that is just used for decoration and does not explicitly support the information in the text will only distract or irritate the reader. Write a conclusion Ive learned through direct observation during usability testing that readers love a concluding sentence that signals to them that they have successfully completed the procedure. Congratulations! Youve just changed the oil in your car! Without a conclusion, theyll turn over the page and ask Is that it? Dont Annoy the Reader! Sounds obvious, but this is cardinal rule of technical writing is broken every day. Typically, when people cant figure out how to do something, their first impulse is to ask a colleague. Their next thought is to telephone someone who might know better than they do perhaps another colleague, or a technical support rep. If they cant find anyone to talk to, as a last resort theyll read something on their own. But keep in mind that before they even pick up your manual, theyre already annoyed that something isnt working as it should, and that no one is there to tell them how to do it right! If at this point you present the reader with something annoying, you run the risk of them throwing up their hands in despair and cursing the documentation forever. The writing in procedures should be transparent. That means that the reader should see right through the writing to the information behind it, just as you look through a picture window to see what the weather is like. If you notice the window, perhaps thats because it has grime and smudges all over it! Some of the greasy fingerprints that annoy readers are poor spelling, typos, sexist or racist language, jargon, clich辿s and idioms, flowery or literary style, digression, poor attempts at humour and even misconceived metaphors When in doubt strike it out! Summary Remember, a well-written procedure: Is short Is clear Uses the active voice Has a title Identifies prerequisites Clearly defines the task Accurately defines the outcome Follows a logical and sequential progression Describes one action per step Uses parallelism Uses graphics appropriately Has a conclusion Does nothing to annoy the reader!