Web Writing That Works!

           A Project of
           The Communication Circle

Guidelines Rants Patterns Poems Services Classes Press Blog Resources About Us Site Map

HomeRants > How to organize a step-by-step procedure. > Put instructions into discrete steps. > Write short, energetic steps.



 

Start off in the imperative!

Put context ahead of the imperative--if you must mention the context at all.

Make instructions for each step short and energetic.

Caution: Use the same verb for the same action over and over.

Write short, energetic steps.

Give orders, where possible. "Do this!" "Do that!"

Begin most instructions with imperative verbs.

  • Not passives ("The door is now to be alarmed.")
  • Not statements of permission ("You may now take one giant step forward.")

You may feel, at first, that ordering people around is impolite.  But most users understand that you are trying to help. 

And the imperative makes clear who should do what. YOU THERE!  Do this!

Start off in the imperative

Put the imperative verb right at the start, wherever you can.  Get the action going right away.

Example: Before

Library Object Selection Process

Selecting one or more objects to place in your temporary library may be accomplished by menu selection. The pointer must be moved into the menu bar, pointing at the Objects menu; the Objects menu must be selected from the menu banner at the top of the design window, and when it opens, Select Objects must be pointed to. Release the mouse button when the Select Objects command highlights.

In the dialog box, a user may specify what types of objects are desired for selection; select as many as desired (but at least one) in the list on the left, titled Objects.

Example: After

Selecting Objects to Place in Your Temporary Library

1. Choose the Select Objects command on the Objects menu.

A dialog box appears, in which you can specify what kind of objects you want to select.

2. Select one or more types in the Objects list, on the left.  

 

Put context ahead of the imperative--if you must mention the context at all.

Occasionally, you have to put something other than a commanding verb up front.

For instance, you may have a step that only part of your audience wants to take. If so, you start that step with an IF clause. "If you are working from home…" That way, people who are part of that group know to read the rest of the step, and others skip it.

If you need to state the context, location, or purpose of the step, do so up front, in a few words, before the verb.  Use brief introductory phrases when setting the scene or explaining the purpose.

  • When done, press the right mouse button.
  • On the x menu, choose y.
  • To complete the drawing, click the right mouse button.

Bad Example:

Here the steps begin with a noun or a confusing introductory phrase. The second step isn't an action at all.

1. The triangle under the Imitate step should be clicked, not the step itself, to bring up the Initialize Imitation Environment Form showing the current library path (the default) and the library path defined in the imitation environment file (im.env).

2. You may want to modify one of these library search paths.

To add or delete a library in the current library path, choose Set Search Path from the Design menu, and edit the path, then return to this window.

To add or delete a library in the imitation environment search path, use the vi editor to edit the im.env file, then return to this window.

3. It is possible to specify the library path defined in your imitation environment (im.env) file, if you want, by clicking the button next to the question about it.
Clicking Apply approves the selection but leaves the form displayed; clicking OK approves the selection, but closes the form.

Revised example:

Now the first and fourth steps begin with verbs. We've revised the introductory phrases so they set the scene or briefly explain the purpose for the action. And the fourth step is unearthed from where it was hidden in the old step three.

1. Left click the triangle under the Imitate step.

Do not click the step itself.

The Initialize Imitation Environment Form appears, showing the current library path, which leads to the default library, and the library path defined in the imitation environment file (im.env).

2. If you want to modify one of the library search paths, do so now.
  • To add or delete a library in the current library path, choose Set Search Path from the Design menu, and edit the path, then return to this window.
  • To add or delete a library in the imitation environment search path, use the vi editor to edit the im.env file, then return to this window.

3. If you want to use the library path defined in your imitation environment (im.env) file, left click that button.

4. Click Apply to approve the selection and leave the form displayed, or OK to approve the selection and close the form.

The Imitation flow chart appears.

Make instructions for each step short and energetic.

Don't ramble.

  • Be direct. Tell people just what to do. Don't make them guess.
  • One meaningful action per step. Not two or three.
  • Don't cram several actions into a single step. One moment at a time.
  • If you are talking to a sophisticated audience, do combine several actions that have minimal results into one step, such as selecting the command and issuing it, or choosing an object and moving it.

The user is asking, "What do I do next?"  That question demands a single action as an answer--not three or four. The ideal step, then, is one meaningful action expressed in one sentence.

  • Meaning is in the mind of the audience.
  • A single meaningful action for a beginner is only a part of an advanced user's simple action.
  • Condense the action into one sentence.
  • If the action is too complex to do that, consider breaking it into several steps, or even a distinct procedure.

Before

This instruction tells you how to enter, then correct an entry, and adds instructions on how to edit an entire entry-material that should be provided in another procedure (how to edit) or in an explanation.

To identify your own objects within the library, you may have the software add a suffix to all objects you place in the library; this suffix is your own identifier, such as your initials. Type a three-character identifier in the Suffix field, if wanted. The identifier will be appended to each object name, to signal that it is yours. If you must rewrite the identifier, use the backspace key to delete, and then retype. Editing the whole entry can be accomplished by tabbing into the field, double-clicking to select the entire entry, backspacing to delete, and retyping.
After

This instruction tells you how to enter the identifier. Comments about initials, and the results go into the explanatory paragraphs. All editing is sent to its own procedure.

3. To identify your own objects within the library, type a three-character identifier in the Suffix field.
You might want to use your initials. These will be added at the end of any object name, to identify the object as yours.

Trouble typing the identifier?  See Editing an Identifier.

 

Caution: Use the same verb for the same action over and over.

Make sure you are consistent in the way you describe the same action.

If you get creative, and use different words for the same idea, people begin to think you are talking about several different actions. They develop elaborate fantasies about the different actions they think you are describing.  They go wrong, fast.

Here are some common ways of describing actions:

  • Click x. (not "click on."
  • Choose (a menu item). Not "select."
  • Select the passage (by dragging through it, say).

But no matter what verb you settle on, use it over and over, any time you mean the same thing.  Smelling a rose is smelling a rose is smelling a rose.

Additional detail on instructions:

 

 

 

 


 

 

Was I supposed to put shaving soap on this brush before I rubbed my face?

 

Home | Guidelines | Rants | Patterns | Poems | Services | Classes | Press | Blog |
Resources | About Us | Site Map

Web Writing that Works!
http://www.WebWritingThatWorks.com
 © 2003 Jonathan and Lisa Price
The Communication Circle
Discuss at HotText@yahoogroups.com
Email us directly at ThePrices@ThePrices.com
Order Hot Text (the book) from Amazon