Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: More Macintosh Toolbox /: Chapter 3 - Help Manager / Using the Help Manager

Providing Text or Pictures for Help Balloons
Use help balloons to provide the user with information that describes or explains interface features of your application. The information you supply in help balloons should follow a few general guidelines in order to provide the most useful information to the user. This section describes these guidelines.
For examples of how your application should use help balloons, observe the help balloons that the Finder, the TeachText application, and system software use.

Defining Help Messages
Use help balloons to explain parts of your application's interface that might confuse a new user or features that could help a user become an expert user. The information you provide in help balloons should identify interface features in your application or describe how to use them.
The help balloon for an item appears when the user moves the cursor to that item. Because the user knows exactly what the text is referring to, this is a powerful method of providing information. But the method has some limitations. There are some kinds of information that help balloons cannot display effectively.

Help balloons can show users what they will accomplish by using onscreen objects, including menu commands, dialog boxes, and tool palettes.
Help balloons can help experienced Macintosh users who prefer to learn programs by using them, rather than by reading manuals.
Help balloons can't help users who don't know what they want to do or users who don't know where to look.
Help balloons can't teach your program by themselves. They can't substitute for task-oriented paper or electronic documentation or training.
Help balloons can't teach novice Macintosh users the concepts they need to know in order to use the Macintosh computer.

Help balloons work best when you keep your audience in mind as you write. Ask yourself these questions when you are planning balloons for your program:

Who will be using your program?
What aspects of your program are users unfamiliar with?
What terminology are your users likely to know?

Unless your application has a specialized audience, it's best to write for users who already know something about using the Macintosh (although they may not be experts) but who don't know much about your application.
Each help balloon should answer at least one of these questions:

What is this? For example, when the user moves the cursor to the item count in the upper-right corner of a Finder window, the Finder displays a help balloon that reads "This is the number of files or folders in this window."
What does this do? For example, when the user moves the cursor to the Find command in the Finder's File menu, the Finder displays a help balloon that reads "Finds and selects items with the characteristics you specify."
What happens when I click this? For example, when the user moves the cursor to the close box of a window, the Window Manager displays a help balloon that first names the object ("Close box") and then explains, "To close this window, click here."

Help messages should be short and easy to understand. You should not include lengthy instructions or numbered steps in help balloons. Use help balloons to clarify the meaning of objects in your application--for example, tool icons in palettes.
Use simple, clear language in the information you provide. Include definitions in help balloons when appropriate.
You can use graphics or styled text in help balloons to illustrate the effects of a command. For example, to demonstrate the effect of the Bold command in a word-processing application, you might use styled text to show a word in boldface.
You can provide separate help balloons for two display states--enabled and dimmed (disabled)--of a menu item. You can also provide separate help balloons for two display states--active and dimmed (inactive)--of a control. The help balloon that you provide for an enabled menu item should explain the effect of choosing the item. The help balloon that you provide for a dimmed menu item should explain why it isn't currently available, or, if more appropriate, how to make it available. Similarly, the help balloon that you provide for an active control should explain the effect of clicking or selecting the control, and the help balloon that you provide for a dimmed control should explain why it isn't currently available, or, if more appropriate, how to make it available.
Complicated dialog boxes can often benefit from help balloons that explain what's essential about the dialog box. You can use help balloons to describe groups of controls rather than individual controls. For example, if a dialog box has several distinct regions that contain radio buttons or checkboxes, you could provide a help balloon for each set of radio buttons, rather than providing a separate balloon for each button.
If you use a function to customize standard dialog boxes, use as many of the existing help balloons as possible. For example, if your application uses any of the standard file dialog boxes and provides an extra button, you can create a help balloon for the extra button, and the Help Manager continues to use the default help balloons for other items in the dialog box.
To make localization easier, you should store your help messages in resources separate from the help resources. To avoid problems with grammar and sentence structure when you localize your application, never combine separately stored phrases into one help message.

Using Clear, Concise Phrases
You can provide up to 255 characters of information using text strings in help balloons. (You can use up to 32 KB if you use styled text.) However, you should include only the most relevant information in the help balloon. To determine what to provide, decide what information would be most useful to a user. This information usually omits
the object's name, which normally doesn't matter to the user, and instead tells what the object is for and what the object does, which does matter to the user.
You might eventually translate your help messages into other languages, so try to keep the messages as short as possible. When translated, your help messages may require more words or longer words--and therefore larger balloons and more screen space. Expect English text to expand 20-30 percent after translation. To keep the translated text within the Help Manager's 255-character limit for text strings, limit English text to approximately 180 characters.
If an item already has a commonly used name, or if it's a special case of a larger category of objects, name it in the balloon. The Finder, for example, displays the message "Drag the title bar to move the window," since title bars and windows are commonly used names. However, you don't need to name everything in your application just so that you can refer to it in a help balloon. For example, because the tip of the help balloon points to the subject of the help balloon, you can easily say "To apply the style, click here," rather than "The Apply button activates the Styles command. Click the button to activate the command."
Many of the items onscreen don't need names. An item needs a name only if the name helps the user remember how to use the application. The following items are likely to need names:

icons that don't already have names on the screen
tools in a palette
controls on a ruler
controls in a paint program
Finder icons whose names can be changed

If you decide to name an item, make sure that the name you use in the balloon matches the name used in other documentation.
For balloons that describe menu items, you can use sentence fragments; the grammatical subject is obvious from the context. For example, the help balloon for the Open command could read "Opens the selected file" rather than "This command opens the selected file"; the grammatical subject is obvious from the context. Using sentence fragments lets users assimilate the message more quickly because they have fewer words to read.
When you describe a menu item or a button, try to use a word that's different from the one that appears onscreen. Using a synonym in this way helps users who aren't sure what the item's name means. For example, the help balloon for a Paste command in the Edit menu might say something like "Inserts the contents of the Clipboard into the document."
Help balloons are usually inappropriate for describing multiple-step procedures, because a help balloon does not stay on the screen while the user performs the various steps. The user may begin a procedure described in a help balloon and then become confused when the information disappears.
You can, however, describe a very simple two-step procedure in a balloon. This is probably most appropriate for a tool in a palette. For example, the balloon for an eraser tool might first define the tool as an eraser and then explain, "To remove parts of your drawing, click this icon, then drag to erase those parts you want to remove."

Using Active Constructions
Try to use short, active phrases in help balloons. Avoid passive constructions. An active construction is more forceful because it communicates how the grammatical subject (usually the user in this context) performs an action. In the sentence "To turn the page, click here," the implied "you" (that is, the user) is the subject, and "click" is the action that the subject performs. Passive constructions show subjects being acted upon rather than performing an action. For example, in the sentence "The page will be turned when this button is clicked," both "page" and "button" are acted upon.
Research suggests that instructional materials are more effective when they present the goal clause before the action clause, helping readers quickly recognize how the information meets their needs. A goal might be "To turn the page," "To calculate the result," or "To apply the style." For example, the message "To turn the page, click here" starts with a goal statement and then describes the action necessary to fulfill it; users find this more helpful than a purely descriptive message like "This button turns the page."
If there is more than one way for the user to achieve a goal, mention only the method that involves the item to which the user is pointing. In other words, if the user is pointing to a button, the balloon should tell the user how to use the button, not how to use a keyboard shortcut for that button. For example, a help balloon for a Save button might state, "To save the changes you have made to the settings in the dialog box, click this button"--but the help balloon should not add "or press the Return key."
If there is more than one method for using the item to which the user is pointing, describe the method that's simplest to explain and understand.

Using Parallel Structure
Use similar syntax for help balloons that describe similar objects. For example, all help balloons that describe buttons should have the same structure. In a style dialog box, you might provide these messages for the buttons: "To see the style, click Apply," "To implement the style, click OK," and "To do nothing to change the previous style, click Cancel."
Users see help balloons provided by many different applications, so a consistent approach within your application helps them to identify types of balloons quickly and to develop realistic expectations about their help messages.

Offering Hints
If there are just a few interesting features in your application that would be difficult to discover, then it's appropriate to use balloons to call those features to users' attention.
But if you want to give a hint or shortcut in a balloon, ask yourself these questions:

Is the balloon reasonably short, even with the hint?
How often will users need the information? If a feature is very obscure and few people will need it, the balloon probably shouldn't describe it.
Are hints and shortcuts available somewhere else--for example, in a "shortcuts" dialog box or a quick-reference card? Not all users will look at balloons. If your program includes many shortcuts and tricks, be sure to list them in other documentation as well.
Does the need for hints indicate the need for a different design? If your application contains many hidden shortcuts and features, then you may need to redesign your application to make these features more easily accessible to users.

If you include a hint or shortcut, put the hint at the bottom of the balloon and separate it from the rest of the message by a blank line. For example, the Clean Up Window command in the Finder's Special menu initially describes the command's effect: "Neatly arranges the icons in the active window." Then there is a blank line followed by a hint: "Tip: for other cleanup commands, hold down the Shift or Option key while choosing this command."

Using Consistent Terminology
You should employ consistent terminology in all your help balloons. Use language that users understand; avoid introducing technical jargon or computer terminology into help balloons. Follow the style and usage standardized by Apple Computer, Inc., in the Apple Publications Style Guide (available through APDA) to make the most effective use of the information and vocabulary with which users are already familiar. A supplement to the Apple Publications Style Guide, titled "How to Write Balloons," spells out the guidelines that Apple writers use for the wording and phrasing of help messages. This supplement also provides many examples of clear and useful help messages as well as counterexamples of types of messages to avoid.

Defining the Help Balloon Position
When you provide a help balloon, you specify its help message, the tip of the help balloon, and the variation code for its preferred position. The tip of the help balloon should point to the object that the help balloon describes. You should specify the tip and the variation code so that the help balloon doesn't obscure the object for which you're providing help. In most cases, the tip of the help balloon should point to an edge of the object.
You should also consider how the Help Manager repositions the balloon if the variation code places it offscreen. "How the Help Manager Displays Balloons" on page 3-7 describes how the Help Manager repositions the help balloon if necessary.