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. > Organize explanations to follow the train of thought.


Why put different types of explanations in separate paragraphs?

Follow the user's thought process

Personalizing the pattern


Organize explanations to follow the train of thought.

Separate any explanations from the step they refer to, because

  • Explanations serve a different function, answering questions that follow up on the instruction in the step.
  • Some of your audience are too impatient to read explanations.  They just want to do the steps, and skip all that other verbiage.
  • You may want to reuse the steps in many different locations, without the relevant explanations.
  • Also, if you offer customization and personalization, people will probably want to be able to pick and choose which types of explanation they want to view or hide.

Explanations tend to proliferate if you let them, so find out which questions your audiences ask most often, so you can decide which elements your audiences want most, out of a list like this:

  • What should I watch out for here? Warning
  • What do you mean by that term you just used in the instruction? Definition
  • What's the result? Feedback or Result
  • Could you show me what my work ought to look like? Illustration
  • What does that show? Caption
  • Could you give me an example showing how this is supposed to work? Example
  • Could you give me a hint here? Tip
  • But I didn't get that result. How can I recover? Troubleshooting or Remediation

(The bold-faced terms are element names, not labels.  You do not have to keep saying, "Look, I am announcing that I am writing a caption." )

Just be clear what kind of object you are creating, what its purpose is, what function it fulfils.  If you are unclear about the purpose of a particular explanation, you should consider dropping it.


Probe your audiences--gently.

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

Creating procedures (A chapter from Hot Text! Web Writign that Works. PDF. 995K, or about 18 minutes at 56k). 

Why put different types of explanations in separate paragraphs?

Carving explanations up into separate paragraphs, each addressing a specific type of question, makes the explanations into distinct elements, so you and your users can reuse, include, or exclude them on the fly.

Planning several distinct explanation types speeds up writing, too, because you are not trying to weave several different kinds of information together into a compelling paragraph.

You are just sorting facts into bins--and in the process, your prose gets simpler, more purposeful, and, because you are just answering one question per paragraph, abrupt.

Yes, some of these paragraphs end up being one sentence, or a single phrase. If that sentence or phrase answers the question, hey, that's all you need. 

Follow the user's thought process

Your visitors have their own questions, which tend to arise in a certain, fairly predictable order.  You could think of these appearing from moment to moment, as the mind ponders the instruction, follows it, and tries to decide whether or not the action was a success. 

Try to figure out what those questions are, and in what order they normally appear.  You'll often find that there is a natural order to the questions that occur to most users after they read your step.

Keep to a standard organization in these follow-up paragraphs, answering each virtual question as it naturally appears.

For example, here is the sequence of questions we've found users ask, sotto voce, as they make their way through procedures for using software.  Imagine they have just read a step.  Now their mind starts worrying. Here are the questions, with suggestions on how to respond.

1. What should I watch out for?

(Put any warnings right after an instruction that could lead users into danger.)

2. What do those strange terms mean?

(Explain any obscure terms in the instruction. Give any supplementary details that will help the user carry out the instruction. "The icon appears in the lower right corner of your screen.")

3. What's the result of doing this?

(Describe the results of carrying out the step. Discuss the results whenever customers are faced with something new, unusual, unexpected, or subtle and hard to notice. Include "how it works" ONLY if user must infer what is going on inside the machine.)

4. Does my result look like yours?

(Display screen shots to show the results, even if you need to repeat pictures. Sometimes you need art to show the result of one action, and then the location of the next step's action.)

5. What do these results mean?

(Explain the results in depth, if necessary.)

6. Could you give me an example of the way this works?

(Give an example. If you think one would help, build the example in three parts: a description of the situation and the purpose of the person in your story, the action that person took, and the result.)

7. Any tips for getting through this maze?

(Offer tips only when they are real extra ideas, not secret warnings, or background.)

8. I'm in trouble: how do I get out?

(Offer troubleshooting advice right when the trouble could happen.)

9. What do I do next?

(When the reasoning behind the sequence is not obvious, suggest why customers should take the next step. The explanation should help motivate customers to continue.)

10. Where can I go for more information?

(Add see-also cross references, if they would really be helpful.)

In most circumstances, you would use only one or two of these elements.  But you need to have a whole set of explanation types ready to go, with a clear idea of the ideal sequence, so that when you realize users may be confused, you can jump in.

Of course, many writers believe that their instructions are so clear that no one could go wrong.  These are all writers who have decided that they do not need to test their instructions on real people. Once you test, you realize how many ways people get get lost after reading a step that you think is supremely simple.

Personalizing the pattern

Individuals have different tastes in explanations.  Some like everything you can give them; others prefer a Spartan procedure, with just a few critical explanations.  Here are two personalized patterns:


Example of revising explanations


Now that you have selected the figure, you can move it. See also: How to Mouse Around. Note: Don't touch the handles, or else you might change the size or shape of the figure. When clicking, you should be careful not to click a nearby figure, or the background, because that way you might be selecting some other object. Note: clicking is putting the tip of the pointer on a line in the figure and pressing the left mouse button.
Be careful not to click the object next to the figure, or the white space around the figure, because you would then be selecting the other object, or, possibly, the rectangle that lies in the background.

To click, place the tip of the pointer on one of the lines of the figure, then press the left mouse button.

When you've clicked the figure, you see little squares appear at the corners of your figure, and in a rectangle around the figure; these squares are called handles.

The handles allow you to resize or reshape your figure. (Don't touch them right now).

Now that you have selected the figure, you can move it.

See also: How to Mouse Around.


What kind of brush was that?


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

Web Writing that Works!
  2002-2004 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