Creating Online Help That Works


	Creating Online Help That Works	Search BWA Web Pages

By: LeRoy Miller
Copyright © 2004 LeRoy L. Miller

To create a successful online help file, know what you're talking about, say it clearly, and stay out of the user's way.

Know your purpose
Know the software
Define everything
Keep it simple
Eliminate verbal clutter
Write short sentences
Stay in the present
Use tables
Make lists
Avoid overcapitalization
Write in English, not Latin

Eliminate screen clutter
Keep the user oriented
Don't use disappearing windows
Use a single browse sequence
Limit jumps in text
Be generous with keywords
Allow multiple points of entry
Keep popups small
Write one topic per topic
Put information where the user can see it

know your purpose

A help file is not a user guide, an online manual, a tutorial, or a marketing piece. The purpose of a help file is to tell the user what they need to know when they need to know it. Anything else defeats the purpose of the help file. Leave it out.

know the software

Know the software as well as the programmer, better than the marketing manager, better than the casual user. You can understand the mechanics of a program, but that's not enough. You have to understand it from the user's point of view. What will the user do with this program? What everyday tasks will they perform? What features will they use most often?

define everything

If it's in the application, put it in the help file: Explain every object on the interface: buttons, drop down boxes, menu items, icons, option buttons --everything. Document every word on the interface: menu commands, tool tips, object labels, and other on-screen text.

keep it simple

Keep the help file focused on its task. Leave out anything that doesn't help the user use the application.

eliminate verbal clutter

Edit your text ruthlessly. Cut out extra words.

Don't Say	Say Instead
If you want to print a header on your report...	To print a header on your report...
To formulate an advanced search, do the following: ...	To formulate an advanced search:..

write short sentences

Keep your sentences short. Break up compound sentences into two shorter ones.

stay in the present

Speak in the present tense. It may be happening in the future to you, but it's happening right now to the user.

Don't Say	Say Instead
When you click the print button, the print dialog box will open.	When you click the print button, the print dialog box opens.

See the next paragraph for an even better way to say this.

speak to the user

Speak directly to the user. Tell them what to do, instead of describing abstract events

Don't Say	Say Instead
When you click the print button, the print dialog box opens.	Click the print button to open the print dialog box.

use tables

Use tables to present information efficiently and eliminate clutter.

before

To make a copyright symbol, hold down the Alt key on the numeric keypad and press 0169. To make a trademark symbol, hold down the Alt key on the numeric keypad and press 0153. To make a registered symbol, hold down the Alt key on the numeric keypad and press 0174.

after

To insert a symbol, hold down the Alt key and type its ASCII number on the numeric keypad.

Symbol	Name	ASCII Number
©	copyright	0169
™	trademark	0153
®	registered	0174

To learn more about using tables and lists to improve readability, see Information Mapping, Inc., the home page of Robert Horn, developer of the information mapping theory.

make lists

Use numbered lists for the steps in a procedure or sequence. Use bulleted lists for a group of related items.

before

To print a portion of the document text, highlight the text you want to print by holding down the right mouse button and dragging, then click the printer icon on the toolbar. When the print dialog box opens, select the number of copies you want, then click the print button.

after

To print a portion of the document text:

Hold down the right mouse button.
Drag the mouse pointer to highlight the text you want to print.
Click the printer icon on the toolbar.
The print dialog box opens.
Select the number of copies.
Click the print button.

don't overcapitalize

German capitalizes every Noun. English doesn't. Overcapitalization makes a Sentence hard to read and contributes to Screen Clutter.

write in english, not latin

Latin abbreviations save time for you, but they slow the reader and may confuse them. Use English. (If you do use Latin abbreviations, at least get them right. Don't say i.e. when you mean e.g.)

Don't Say	Say Instead
e.g.	for example
i.e.	that is (or rewrite the sentence)
etc.	rewrite the sentence

eliminate screen clutter

Everything on the screen competes with everything else. Keep the visual presentation simple. Don't distract from the content.

keep the user oriented

Day One: The first hypertext document is created. Day Two: The phrase "lost in hyperspace" is coined. Keeping the user from getting lost is one of the keys to creating a successful help file

A sure way to confuse readers is to use disappearing windows -- windows that vanish from the screen when the user takes some action, such as clicking a tab or button. Don't use them. They startle the user and are disorienting. If you use a secondary window, keep the main window open too. Microsoft help files are especially bad in this regard. Don't use them as models.

use a single browse sequence

Put all the major topics in the same browse sequence. A browse sequence lets the user read topics in a structured order. By having a single browse sequence that runs from beginning to end, the user can follow any topic through to its logical conclusion. If they want, they can start at the beginning of the file and read all the topics through to the end. (There can be good reasons to break this rule, especially for large help files.)

limit jumps in text

Don't overload your text with jumps. They make the text hard to read, and they tempt the user to leave a topic prematurely. Where possible, put the jumps in a See Also or Related Topics list at the bottom of the topic.

be generous with keywords

Keywords point users to topics you decide they should read. They are the words that appear in the Index tab. All the words in the help file appear in the Find tab. Searching the Index is a much more structured and efficient way for the user to find information -- if you did your job.

allow multiple points of entry

Let the user get help with no more than two mouse clicks or key presses. Give them multiple ways to access the help system:

Help > Contents entry on the menu bar
F1 help
A Help button on every dialog box. (Don't force the user to close a dialog box to learn how to use it.)
What's This help

keep popups small

Use popups for definitions and other brief references. Don't put any of the following in popups:

Jumps
Other popups
Screen captures, diagrams, or graphics
Lots of text

There are good reasons for limiting what you put in popups:

You can't print them.
They don't appear in the history list.
You can't get to them with the back button.
You can't bookmark them.
You can't annotate them.
They disappear quickly.

write one topic per topic

Limit each help topic to one main idea. Create links to closely related topics.

put the information where the user can see it

Don't make the user click a hypertext link to see information that can be displayed just as easily at the link site.