Web Writing That Works!

           A Project of
           The Communication Circle

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

HomePatterns > How to write FAQs > Put instructions into numbered steps


 

One meaningful action per step, please.

Begin each instruction with a verb in the imperative, if possible.

Exceptions to the rule

Skip the pitch

Adopt the user's perspective

Separate the instructions from any explanatory material.

Organize the explanations

Can steps be links?

Put instructions into numbered steps

Breaking your instructions out into numbered steps makes them more effective. Why? With numbers...

  • People understand the sequence better.
  • They skip fewer steps.
  • They succeed more often.

One meaningful action per step, please.

Don't try to cram two or three actions into a single instruction, because people do the first, then the third, or get confused.

Yes,  piggybacking makes your procedure look simple, because there are fewer steps.

But the individual steps, clotted with more actions than a user can absorb at once, end up failing.

What's meaningful

That depends on the guest. For instance, beginners find command lines a tough way to interact with a program, and consider typing DIR a major action, and pressing Enter another big step.

But experienced DOS aficionados understand "Enter DIR" to mean "Type these letters and hit the Enter key."

Here's a case where personalization can help you differentiate your FAQs by skill level. The instructions for experts generally compress more actions into a single step, and skip most explanations.

Related article

Writing in a genre (Full chapter from Hot Text, in PDF, 770K, or about 13 minutes at 56K)

Answers to Frequently Asked Questions (FAQs) from Hot Text, Web Writing that Works (PDF, 995K, or about 18 minutes at 56K)

Hurray for FAQs (PricePoint)

Begin each instruction with a verb in the imperative, if possible.

Don't say what the users can do, or may do, or might do. Tell them what to do.

You may feel you are being rude, but bossing the user around is actually a courtesy, because you save time, and make clear that, at this point, the user really must do x, y, or z. No maybes, then.

Exceptions to the rule

Q: What can you put before the verb?

A: Motive or goal.

If you have to say why people should do the step, or what their goal might be, start with the purpose, and then move to the action.

Example: "To confirm your changes, click Change."

If you need to say exactly where to act, put that first, too. "

Example: At the bottom of the license, click Submit."

In these ways, users know up front what the point is, and where to look. Knowing the goal, and the locus of operations will help them grasp the instruction better.

Also, putting the goal, motive, purpose, or location first tends to follow psychology more closely: first you have a goal, then you look around for an affordance to operate on, then you act. (Evaluating whether you have succeeded comes later--in a following paragraph, if ever).

Skip the pitch

Don't pretend you are writing instructions, and then decline into marketing talk.

Example: 3. Using Find Topics is a quick, easy, and powerful way to describe the particular product you may be looking for."

Oh gee, that's wonderful.

But that text does not answer the basic question, "What do I do next?" Giving me an ad instead of a step just makes me mad.

Adopt the user's perspective

Avoid the system perspective.

You are not an engineer writing specs, describing how the system is supposed to work. You are giving a user instructions.

  • You  are not responding to the user's needs if you write something like "The system requires your billing and shipping information."
  • Switch your perspective. "Please enter your billing and shipping information."

Separate the instructions from any explanatory material.

Put the explanations in following paragraphs.

Each step answers one question: "What should I do next?"

The explanations tend to answer ancillary questions, such as "What does that term mean? What's the result?"

So the explanations are different elements, with different responsibilities, and they deserve their own separate identities, as separate paragraphs.

Breaking explanations away from the steps means the impatient user can just read the steps, and do those, and never read your explanations.

Nervous folks, though, want their sweaty palms held tightly, and seem grateful for the separation, which makes clear "You do this," and "Here's more information if you want it."

Gradually unfolding works better than jamming all the information into a single paragraph.

Also, if you are working in an object-oriented environment, you are going to want to be able to identify, and omit, explanations when you send this stuff out to a mobile phone, or turn it into a quick reference. Explanations, then, are different objects.

Organize the explanations

Consider the order of explanations, and try to follow the user's likely sequence of follow-up questions.

For instance, people usually ask what a particular term means, in the instruction, before carrying out the instruction, so a definition of a concept would come pretty close after the instruction, before any description of the result of the action.

Whenever people recognize that they are reading a series of instructions, they expect the structure to be strictly chronological.

They expect everything--steps, explanations, pictures--to show up in exactly the order they experience carrying out the instructions.

When you first think about it, the chronological approach seems simple, but if you really try to apply it to your answers, you'll find that in many little ways you have jumped ahead of yourself, or forgotten to mention some little action you take for granted, or you have actually scrambled the order of steps.

Creating good instructions means beating on the sequence until you're certain that you have evoked the moment-to-moment experience.

Can steps be links?

Yes. If each step is actually described in a separate answer, and the step really involves several actions, you can tell people, "Enter your credit card information," making that instruction a link to the full details on entering the credit card info.

The great end of life is not knowledge but action.

—Thomas Huxley, Science and Culture

 

Tell me how to solve my problem.

 

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

Web Writing that Works!
http://www.WebWritingThatWorks.com
 © 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