C H A P T E R 1 4

User Help and Assistants

Avoid adding items to the Help menu that essentially lead to the same place— your help book. Multiple entries that open Help Viewer can be confusing; differences between sections of your help book may not be as obvious to users as you think they are. Navigating between sections of a help book is typically best handled by providing links in the Help Viewer window.

■Help buttons. When necessary, you can use a Help button, typically placed in the lower-left corner of a dialog or window, to provide easy access to specific sections of your help. When a user clicks a Help button, send either a search term or an anchor lookup (which leads to a specific page or pages) to Help Viewer.

It’s not necessary for every dialog and window in your application to have a Help button. If there is no contextually relevant information in the help, don’t display a Help button.

■Contextual Help menu item. If contextually appropriate help content is available for an object being pointed to, the first item in the contextual menu is Help. As with help buttons, the menu item can send either a search term or an anchor lookup to Help Viewer.

Help Tags

Help tags are short messages that appear when the user leaves the pointer hovering over an interface element for a few seconds. When the pointer leaves the object, the tag vanishes. Use help tags to assist users in identifying the purpose of interface elements. You can define an object’s help tag in Interface Builder for Carbon and Cocoa applications.

The text of the help tags should

■name an object only if the name is relevant to its function and does not have a text label

■briefly describe what the object does

■reflect the current state of the interface item or be state-independent. You can check the state of the item (dimmed, selected, and so on) before displaying the tag.

238Help Tags

Apple Computer, Inc. June 2002

C H A P T E R 1 4

User Help and Assistants

For example, the help tag for a button labeled “Forward” in an email program might read “Send the selected message to someone else.” This provides more detail than the button label, but does not repeat it, and it explains that a message must be selected to enable the button.

It is not necessary for every object to have a help tag. Don’t provide them for common interface elements, menu items, or items that are self-explanatory or obvious.

If necessary, Carbon developers can implement expanded help tags—text that replaces the original help tag and that further explains the control’s function. Users display an expanded help tag by pressing the Command key. Not every tag needs an expanded state.

Figure 14-1 A help tag and an expanded help tag

Help tags should always appear in the same place, regardless of the pointer location. The default position for help tags in Carbon applications is below the control, centered horizontally (if necessary, this position can be changed on a per-tag basis).

Help Tag Guidelines

Here are some guidelines to help you create effective tag messages.

■Use the fewest words possible. Try to keep your tags to a maximum of 60 to 75 characters. Since help tags are always on, it is important to keep your tag text unobtrusive—that is, short—and useful. Present one concept per tag and make sure the concept is directly related to the item. Localization lengthens the text by 20 to 30 percent, which is another good reason to keep the tag short.

■Write the main help tag in any of these ways, depending on the interface you’re documenting:

Apple Computer, Inc. June 2002

C H A P T E R 1 4

User Help and Assistants

■Describe what the user will accomplish by using the control. Examples: “Add or remove a language from your list.” “Reduce red tint in the selected area.” Most help tags can use this format.

■Give extra information to explain the results of the user’s action. This kind of tag is most effective in an interface that already includes some instructional text, because the tag and the interface text work together to describe what the control does and how the user manipulates it.

■Define terms that may be unknown to the user. This kind of tag should be used only if the interface already contains instructions to the user.

■You can create contextually sensitive help tags but you don’t have to; the same text can appear when an item is selected, dimmed, and so on. By describing what the item accomplishes, you may help the user understand the current state of the control even if the tag is applicable to all situations.

■Use help tags to provide functional information for controls that are unique to your application. Don’t tag window controls, scroll bars, and other parts of the standard Mac OS X interface.

■Don’t put the item’s name in the tag unless the name helps the user and isn’t available onscreen. If an item is referred to by name in the documentation and in the tag, make sure the names match.

■You can use a sentence fragment beginning with a verb, for example, “Restores default settings.” You can also omit articles to limit the size of the tag. If the tag text is a complete sentence, end it with a period.

■Describe only the item the user points to.

■Use help tags primarily to provide necessary information, rather than incidental tips.

■If you implement an expanded tag to add another layer of information, don’t repeat the text in the original tag. An expanded tag should do one of the following:

■More fully explain or describe the results of the action described in the small help tag.

Help tag: Shuffles the play order.

Expanded tag: Plays the current list of songs in random order.

240Help Tags

Apple Computer, Inc. June 2002