Designing Effective Online Help

Introduction

Users don't read online help the same way they read printed manuals. When users go to online help they usually have a specific question they want an immediate answer to. They want that answer fast. If they can't find the information they want after a few tries, they often conclude the online help is useless. They might also get pissed off and call up tech support to complain. If that happens, tech support will chew YOU out! :-) This article looks into some things you can do to make effective online help and prevent user frustration.

Getting to the Point

Because users want information, and want it fast, they don't want to read through pages and pages of useless information. You have to get right to the point. The best way to get to the point is avoid unnecessary banter. Including the equivalent of 20 pages of company history is a no-no. Marketing pitches are also very bad. If someone has spent their money on a product, they don't want to have to sit through a repeat of the sales pitch (especially if the product doesn't live up to the promises of the sales pitch).

How do you get to the point? You can make introductory paragraphs short. Two or three sentences long should be good enough. You should include only relevant information, leaving out marketing.

Speaking plainly

If you're an English major, you'll have to fight the urge to produce documentation that is full of, well ... big words. Online help is supposed to help people learn. They shouldn't have to use a dictionary to figure out the meaning of the words you're using on top of having to learn how to use the product.

The best thing to do is use smaller words that are in common use. This makes your online help easier to understand. Users will be able to understand the information more easily and that will put your users at ease. You should avoid using adjectives and adverbs. For example, "Use the widget to produce graphics," and not "Use the widget to quickly and effortlessly produce graphics." You should also avoid marketing, which is used to sound impressive while conveying no real information. "The widget dynamically promotes effective graphical solutions," is just grotesque and pointless. Finally, avoid buzzwords: solution, elucidate, empowers and proactive are just a few of the ones that really irritate me.

I think I can demonstrate what I mean when I say "speak plainly" by relating an anecdote. I recently went into a rest room stall in an office building. I noticed a green note taped to the back of the stall door. A white note was taped over the green note. Being curious, I lifted off the white note to see what was written on the green note. The green note read something like this "Attention: Due to low pressure in this facility, excessive use of paper products necessitates frequent attention." The white note read "Flush often to avoid backup."

Which note is easier to understand?

Writing short sentences

Sentence length impacts a reader's ability to comprehend the meaning of a sentence. Users don't care how well you can link five sentences together. They're not looking for poetry. They want information presented in a format they feel comfortable with. That usually means shorter sentences that deliver only pertinent information.

There are two ways to reduce sentence length. First, you should use active voice. For example, you should write "John hit Bob," not "Bob was hit by John." Second, you should use declarative and imperative sentences. This is especially important when you're writing instructions, for example "Click the X button."

Creating short topics

While short sentences make it easier for users to learn new concepts, short topics make new users feel more comfortable with the learning process. Let's face it, if you look at a body of text and it looks long, you'll grimace and avoid reading it. I did just that quite frequently when I was in college. The same body of text broken up into smaller sections tricks users into thinking they're not reading as much. The current article is a perfect example. Click here to see the entire content of this article on one page. It's pretty daunting.

A daunted user is an unhappy user. They'll sooner call up tech support and complain about the product before reading the online help if it looks like an excerpt from War and Peace. Some people say that you shouldn't have more than 10 lines of text per topic. The rule I try to follow is to make sure users don't have to use their vertical scroll bar (though I break this rule on several of my web pages).

I should mention here that when you're producing online help, be sure you don't force your users to use the horizontal scroll bar. It makes reading difficult and time consuming. Plus, it's just plain annoying. The best way to avoid the horizontal scroll bar is to define a size for the online help window and produce everything so that it fits into that space. If you have to use graphics that are larger than the online help window, you might want to use a popup link that appears in a second window.

Linking

The beauty of online help is that you can link information in one topic to information in other topics. Examples of some common links include table of contents entries, index entries, site map entries, see also, definition popups, and related information links.

Links make it easy for users to find the answer to their questions. It also allows users to find information related to the topic they are reading about. This means that users can access that information with greater speed and learn the product faster. It will make the user feel like they can learn the product! In the end, that's what you want!

When you're creating links, you should make it clear what sort of information the link will take the users to. If users have to click on several different links to find what they want, you're not using your links effectively. For example, "The company's new product line," is actually pretty vague. The link could be a link for the company, or it could be a link for the company's product line. "Click here to view a list of new products," or "The company's new products," are both much better because users can figure out what information the link jumps to.

While links are a great tool, too many links on a page can be confusing. You should limit your links to only pertinent information. For instance, a topic that details information about a database form may have links to how-tos that use the form and definition popups that explain any key terms discussed within the topic. The form can also appear in the table of contents and the index.

Writing with internationalization in mind

While you can produce very effective online help by following the suggestions I've mentioned in this article, you must keep one thing in mind. These suggestions are based on creating online help for domestic, not international, use.

If you find yourself producing online help for an international audience, there are a few things you should keep in mind.

First, avoid humor. While it's a good idea to avoid humor in general, it's especially important to leave it out of documentation that is for international audiences. Humor is often times culturally specific, so what might be funny in one country may be completely offensive in another. Moreover, jokes may loose their meaning in translation, leaving international users wondering why something is included in the online help.

You should also avoid slang, jargon and culturally specific references. Much like humor, these items may not translate into the new language, or may not make sense to international users.

Finally, if you're writing in English, you should attempt to always use Latinate vocabulary. For instance, you should write "examine" instead of "look into," or "accelerate" instead of "speed up." While this is counter to the guidelines set out by the Plain English Network, research shows that international users have an easier time understanding Latinate vocabulary. (see Emily A. Thrush's "Plain English? A Study of Plain English Vocabulary and International Audiences" Technical Communications, Volume 48, number 3)

Wrap up

You must remember that your goal as a technical writer is to produce material that teaches users about a product or service. The more effective your documentation, the least likely your users are to declare your online help useless and the product a fraud. You'll also avoid numerous tech support calls that could have been avoided if you had followed the suggestions in this article.

I must confess that what I've outlined here is only a quick overview. I could write volumes on each one of these topics, but I'm sure my wife wouldn't be too happy with the amount of computer time that would involve. So, if you've got the general idea from what I've written, great! You can find more in-depth information through those links. You can also buy Standards for Online Communication. It's a GREAT book.

---