Return to How to

Editing procedures and instructions

Procedural and instructional material is written for a variety of purposes, for example:

  • Training new staff members
  • Recording “the way we do things” in an organisation, as part of a quality process
  • Helping people make a decision, for example on what item they wish to purchase
  • Telling purchasers of a product how to assemble or use it

(You can probably think of other situations.)

What should be included in a procedure?

  1. A statement of the purpose of the procedure, the goal, or intended or expected outcome. This can be as simple as a lead-in sentence such as “To save the file after editing it” or “To unpack and set up the printer”, or it could be a more detailed statement putting the procedure into context of how, when and where it should be performed.
  2. If relevant, a statement of any prerequisites.
    • Must something else (perhaps some other procedure) be completed before this procedure can be started?
    • Does the reader need any documents, information or equipment?
  3. Step by step instructions.
  4. A statement of what happens next.
    • How do readers know if the procedure has been successful? If it wasn’t successful, what should they do next?
    • Does this procedure lead into another? (Is it a prerequisite for something else?)

General principles for editing procedures and instructions

  • Change ordinary paragraphs into numbered steps, or a style called “playscript” (see below). Readers find these constructions easier to read and understand, and they can keep track of their place more easily.
  • Speak directly to the reader—use “do this” language.
  • Give consequences first, so readers don’t get an unpleasant surprise. For example, change “Press the DEL key to delete the file.” to “To delete the file, press the DEL key.”
  • If several alternative choices are involved at one place in the procedure, put the choices in a bullet list or small table within the numbered step, so it’s clear that all the choices are part of the same step.
  • Ensure that steps are in logical order. Even if you are not familiar with the topic, you can look for words like “before you do x” and make sure that step is in the correct sequence.
  • If the reader’s choice in a step leads to branching of the procedure (and what the reader does from that point on varies considerably), split the procedure into several procedures, rather than trying to include everything in one list and possibly confusing readers about exactly what they are supposed to do.
  • A common question is whether to include trouble-shooting information in a procedure.
    • If the trouble-shooting instructions are longer than a sentence, and the problem is uncommon, usually it’s better to say “If this doesn’t work, go to page 25 to learn how to fix it. Then come back here and finish this procedure.”
    • If “fixing it” can be described very briefly, include it in the main procedure. Otherwise readers will go off to find the fix, be irritated that it was so easy, then likely get lost trying to find their way back to where they were. (This is a great place to use hypertext, if what you’re editing will be available online.)
  • If a decision at one step means the reader can skip several steps, but otherwise there is no difference in the rest of the procedure, saying “skip to step xx” should not be confusing.

Using Playscripts

According to Brockmann (1990), “Playscript was originally developed in the early 1960s by Leslie Matthies (1977) to show how to integrate the activities of a number of people involved in one project. Its two-column formatting of information promotes readers’ ability to skim and scan—the major reading strategies” of people at work.

Example of playscript format (adapted from Matthies, 1977):

Daily Time Collecting

Actors

Actions

Executive secretary

  1. Upon receipt of time cards, sort them by department and place in Summary Envelope.
  2. Deliver to department clerks.

Department clerk

  1. Distribute time cards to all employees.

Employees (all)

  1. Prepare time cards as instructed.
  2. Send to department clerk.

Department clerk

  1. Collect all time cards at end of shift.
  2. Calculate regular time and overtime.
  3. Post totals, with grand total for each job, on Summary Envelope.
  4. Place all time cards for the day in the Summary Envelope; fill in date on the envelope.
  5. Deliver the Summary Envelope to the Human Resources Group by 10:00 am of the following day.

Human Resources Group

  1. Calculate regular time and overtime by job from all departments, then post to Project Expenditure Work Sheet.
  2. Send all time cards to the payroll section of Accounting.
  3. Return Summary Envelope to department clerk to be filed as a permanent record.

An editing exercise: What’s right and wrong with this procedure?

Click over to https://jeanweber.com/howto/procex.htm, for a real-life editing exercise.

References

Brockmann, R. John, Writing Better Computer User Documentation, John Wiley & Sons, 1990.

Matthies, Leslie A., The New Playscript Procedure, Management Tool for Action, Stamford, Conn.: Office Publications Inc., 1977.

Last updated 16 April 2002