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. > Separate explanations from steps



 

Separate explanations from steps

A common vice among procedure writers is blending chatter with instructions, explaining a few things at the same time as issuing an instruction, or even putting an explanation in the same format as a step, so someone tries to act on a description.

When explanations are entangled with instructions, everyone--beginner and expert alike--has to slow down to figure out what to do.

You confuse people.

Most people expect that each step will contain an action to perform, not a concept to understand, or a comment on the action.

If a step needs handholding advice, decide where you're going to put the advice--in an introduction or in an explanation. Then move the advice.

Bad example:

In this example, Step 7 begins with the result of Step 6, then gives the users two actions to undertake, and then states the result. Too much!

6. Choose Print on the File menu.

7. You see the Print dialog box. Enter the number of copies that you want, and click OK. In a moment, your document starts printing.

Better:

In the revised procedure, each action gets its own step. Each explanation gets its own separate paragraph, indented, in plain text, to distinguish it from the steps. 6. Choose Print on the File menu. You see the Print dialog box.

6. Choose Print on the File menu.

7. Enter the number of copies that you want.

8. Click OK.

In a moment, your document starts printing.

Additional detail on instructions:

Format steps so they stand out

Write short, energetic steps.

How many steps?

Resources:

Probe your audiences--gently.

Help (A chapter from Hot Text: Web Writing that Works. PDF: 995K, or about 18 minutes at 56K).

 

 

 

 


 

 

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