Publishers of technology books, eBooks, and videos for creative people

Home > Articles > Web Design & Development > Usability

Web Design Reference Guide

Hosted by

Web Writing That Works: Writing Help That Really Helps

Last updated Oct 17, 2003.

By Jonathan and Lisa Price

When they need help, most people ask a neighbor, poke around on the web, or call the tech support people—looking at Help is near the end of their list. So you have to ask yourself:

Do I really need a separate Help section?

Maybe not. If you have a robust FAQ, and you have a lot of embedded customer assistance (labels, instructions, even pop-ups), you may be able to finesse building a special section called Help.

Some sites eliminate a Help section because they often jump to helpful pages from unusual tools (such as the Virtual Model in Lands’ End, or the 1-Click feature at Amazon), or from content that they know is always causing people grief—such as shipping rates, delivery dates, or restrictive policies. The good news is that a customer can get help quickly; the bad news is that there is no comprehensive source of information. If the customer only has one question, and you answer it immediately, fine. But what if the customer needs to jump around a bit to resolve a problem that you didn't anticipate? Then you're likely to seem, um, unhelpful.

Occasionally a site announces Help, and offers a page with a dozen links, but those links take you to existing pages. For example, if you're thinking of going to a museum and you can’t find the hours, you click Help, and you see an item for Hours. But, when you go to that page, you discover that the information existed out in the regular site, not in some special Help page. Fair enough. But after people discover that your make-believe Help page is just a bunch of links, they may conclude that you are a little arrogant. You're essentially saying: we are convinced we've answered all your questions, so we're not going to bother making up a special section devoted to Help.

How should I organize a Help or FAQ section?

Use card sorting with your customers. Give them a set of cards with all your potential topics and ask people to arrange them in groups, telling you what they call that group. In this way, you can build a menu system based on the terms that real customers use—not the in-house phrases that you use.

In the names of topics that appear in your menus, distinguish between step-by-step instructions and conceptual information. If you have an FAQ, methodically assign "How" to instructions, and "What is" or "About" to concepts. If you have to post a bunch of rules (like eBay), label those clearly as rules or policies. People often know what kind of information they want, and they get frustrated if you seem to be offering a how-to, and just give them history, or philosophy.

Be predictable. Let people know in advance what kind of information the topic will provide.

If you offer chat, or personal agents, advertise them heavily on the top page in Help. I know you don’t want to encourage a lot of phone calls, because you pay the support reps so much money...but from a customer’s point of view, any company that dares publish its support line prominently is showing its heart. Don’t force people to read all that prose you created.

What are the big problems with most Help topics?

Too much text. You know you have to write marketing copy in short paragraphs, with plenty of short sentences. Why not do Help that way? No one likes to read text on screen, particularly not great masses of text. Be kind: write less.

Not enough bullets. Whenever you get a series of items, break them out into a bulleted list (if they are all options, with no particular sequence) or a numbered list (if there is some definite order). These lists open up the page, encourage skimming, and relieve pressure on the eye.

Not enough arrays. Go to tables, where you can. If you have information with repeated categories, think columns. Providing a table frees the customers to skip down to the row that has the information they are after. Never make people read more than they need to.

Not enough action. If you can link right to My Account, do so, rather than just talking about it. If you can take me right to the tool that lets me enter my measurements, go! If you have a neat little utility that solves the problem, bring it up immediately. Your job is not to just write a lot of text. Focus on the actions that the customers might want to take—and enable those.

Not enough air. You know how those big dark blocks of text discourage the eye. Open things up. Put space between the topics, and between paragraphs. Let me skim.

Not enough art. Show me a screenshot, or the relevant corner of the screen, where I should click. If you're talking about a tool in your interface, show me what it looks like, in context—that is, with a large enough picture to show its surroundings, so I can find it. You spent all that money creating a graphic look...why abandon graphics when you're offering help?

Too much marketing. Answer the damn question. Stop covering up. If your policy is to refuse returns after 30 days, say so. Do not go all mealy-mouthed on us. Yes, you need to keep marketing points in mind as you write, but do not let them blot out the information that the customer needs. If the facts are disappointing, fix the site. If you find you are laboring to cover something up, try to change the situation, and if you can’t get that done, apologize...and, oh yea, tell the truth. It helps.

Too many inline links. When you sprinkle your running text with links, you risk losing people before they finish a sentence. Don’t interrupt yourself. Move links to the end of the sentence, or, better, to the end of the paragraph. If you have more than two links, break them out as a list.

Inconsistent approach. In one place, you have numbered steps; in another you fold all the steps into one continuous paragraph, making them hard to follow. In another place, you answer a question quickly, but in another you sound like a professor leading up to a well qualified and fully substantiated conclusion. Develop a style guide that spells out how you're going to do the basics—procedures, for instance, and basic concepts.

What if I have a lot of information?

Start off with a multi-level menu system in the center of the page, where you show all the major groups of topics, and some or all of the subtopics—a kind of site map for all of the Help topics. Think of home pages like those of CNN or The New York Times.

Yes, this mass of topics can be a little intimidating, but you are offering people a chance to narrow down their browsing BEFORE they go down the wrong path.

You are also showing them how you have organized the topics, and if they are doing any extensive investigation, they will have better success when they start with a general sense of the lay of the land.

When you go to one of the topics that has a bunch of subtopics tied to it, unfold gradually. Figure out what the top concerns are, address those, then provide a well-organized set of links to related topics.

How can I give step-by-step instructions that people can really follow?

Instructions are the guts of your Help or FAQ because people come looking for a quick nudge in the right direction to accomplish a task they're sure they can do on your site. They do not want to read a lot. They just want to find the product, buy it, and get out. Or they want to finish filling out a form, or checking out. The last thing they want is more work.

Many Help systems hide the actual steps, burying them inside long, long paragraphs. Break the actions out into numbered steps. If it is something the customer should do, give it a number, and format it so that it’s obviously a step.

Cut the introductions. No overviews. No leisurely lead up to the actual problem. No statement of concern or policy.

If the customer has to do something, make it a step—not a prerequisite buried in a convoluted first paragraph.

Clear explanations out of the steps. Keep the steps focused on actions. One action per step. If you must explain what you just said, put that info in a separate paragraph, formatted differently. For instance, indent it, indicating that it is subordinate to the step and follows it.

Use the imperative. Tell me what to do. Do not tell me that I "may" do something. Should I or not? Your first word should be a verb, directing me to do something. "Click this... enter that." If you really need to say where, OK, put that ahead of the verb. "In the dialog, click OK." But strip other debris out of the way, so you can move that verb up to the front of the step.

Please do not make a numbered step out of a result. If the previous step brought up a green screen, and you want to tell me that, put it in an explanatory paragraph. The idea of numbering steps is to telegraph that these are the actions I should take, in this order. When you cheat, and put other information into a numbered step, you frustrate and confuse me.

Empathize with your customers. To produce a good step, you have to consider a multitude of possibilities, while focusing on the experience of the user, moment to moment.

What are my users thinking?

What are their circumstances?

How is their situation different from mine?

How can I make clear exactly what to do?

How can I keep them from going wrong?

Test. Have typical customers try out your steps in front of you. No need for statistical validity. If you can test five or six people, you'll see whether your procedure works...or more likely, where it is ambiguous, or unclear. Or, worse, downright wrong.

Testing is embarrassing because it reveals your lack of imagination. You never imagined that they would interpret that phrase in THAT way. Now you know.

Test, rewrite, test again. And, yes, you should be right there in the room, watching, and talking with the participant. You wrote the instructions, so you are very sensitive to any hesitation or slowdowns. Official Quality Assurance or Usability people do not know the struggle you went through to write the steps, so they will not be as aware of areas where the user is going wrong, or getting upset. Run the test yourself!

Expect to rewrite. Steps look easy to write, but they take more rewriting than almost anything else in your Help or FAQ. As you learn more about the actual action, you begin to see many ways people could go off on a tangent, choose alternate options, or just make mistakes. Quickly written, ill-considered or half-thought-out steps lead readers to make mistakes, slow them down, and increase their sense of helplessness.

What should I do about terms that seem to confuse my customers?

Make up a glossary, and link to the definitions throughout the help. It’s OK to popup the definitions when the customer hovers over a term that you have featured in colored text. If you make the term into a link, bring up a smaller window, so that the customer can still see the original help page.

If you have a bunch of acronyms, include those with their expanded versions in the glossary, or build a separate acronym list.

By separating these definitions from the running text, you avoid repeating yourself, but allow the customer to get that quick lookup whenever you mention the term.

What if I have to describe a difficult concept?

What’s a network? What’s a protocol? What is lift?

Most sites do a lousy job defining concepts like these, which are crucial for the customer to understand before getting down to work or making a key decision.

You can sometimes see the writers fumbling around, starting off to write an essay, then getting distracted, focusing in on some little detail, then reminiscing about how the idea came up in the first place, and so on.

And, despite all the verbiage, the conceptual material rarely answers the questions that users ask.

Conceptual material—explaining an idea, a general theme, an abstract notion—must be organized to respond to users’ questions, methodically and consistently. Otherwise, you waste our time.

You need a pattern, if you're going to articulate your concept. If you must explain a concept, don’t try to pour every point into a single long passage. Break the information up into a series of discrete modules.

But what modules make sense?

Research by major high-tech companies such as Microsoft, Hewlett-Packard, and IBM suggests that when people look up an idea, a term, or a concept, they want several different types of information, in a particular sequence:

A general idea of what you are talking about

Background and context

Step-by-step instructions for using the concept

Resources for more information

The Basic Pattern

Here’s a simple, but effective, pattern for articulating a concept:





You may not need all this detail. But if you follow the basic pattern, you’ll improve the likelihood that customers understand what you are talking about.

The Overview answers broad questions such as:

  • What is the idea? (Definition).
  • How is this concept like or unlike similar ones? (Distinctions).
  • What good is the concept to me? (Benefits).
  • Who should pay attention to the concept? (Stakeholders).

The section devoted to Understanding answers more focused questions such as:

  • Where did this concept come from? (Background).
  • How can you justify your particular interpretation, slant, angle, or improvement? (Rationale).
  • Where does this concept fit into your approach? (Context).
  • What are the key pieces of this idea, if any? (Components, with diagram).
  • How does this idea relate to various processes, process sets, decisions, long-range goals? (Importance).
  • Can you give me some advice about this idea? (Best Practices).
  • Can you illustrate this idea? (Examples and non-examples).

The section on Using the concept answers questions about acting with the idea, such as:

  • When is this idea important? (Scenarios).
  • In what processes is the concept key? (Processes).
  • In what procedures is this concept key? (Procedures).

The section on Resources provides links to:

  • Other concepts
  • Processes
  • Procedures
  • Troubleshooting

(Each section contains links to resources on other pages.)

Figure 2

Figure 2 Expanded diagram of the Concept pattern

How can I keep improving my Help?

On every topic, ask if the information was OK.

If not, ask for suggestions.

Take a look at Microsoft’s online help. At the end of every topic, there’s a request for feedback. They really use this information to identify weak topics, and revise those. Writers are evaluated, in part, on the trajectory of approval: the idea is to get better, week after week.

Of course, you may not get as many comments as Microsoft does. But you can use the suggestions, and the raw rankings (OK, not OK) to gauge which topics need attention. Sometimes the comments point out areas of confusion, words that were ambiguous, missing steps. Other times, they just complain. But if you read them all, you can find out how to be more helpful.

Analyzing web logs and failed searches can tip you off to topics of concern, and topics that people didn’t recognize as relevant (signaling a need to redo the name of the topic, at the least). But these are indirect measures. Feedback directly from your customers is the most helpful for improving Help.

Ultimately, you have to think about your attitude. Do you genuinely want to serve? If you do, you will care—intensely—about the customer’s reactions. Write with that attitude in the forefront of your brain, and your prose will be more considerate, thoughtful, even empathetic. That tone alone will reassure nervous or irritated customers. And when you ask for their ideas on how to improve—and thank them by return email—you are beginning to turn a potential abandoned shopping cart into a repeat customer.