C H A P T E R 6

Using Mac OS X Technologies

User Assistance

Mac OS X supports two user help components: Apple Help and help tags. Help tags allow you to provide temporary context-sensitive help whereas Apple Help allows you to provide a more thorough discussion of a topic or procedure.

Use these mechanisms to provide user help in your application instead of using help mechanisms that are specific to your application. When users refer to help, it is usually because they are having difficulty accomplishing a task and therefore might be frustrated. This is not a good time to make them learn yet another task, such as figuring out a help viewing mechanism that differs from the one they use in all the other applications on their computer.

Apple Help

With AppleHelp, you can display HTML files in HelpViewer, a browser-like application designed for displaying and searching help documents. Help Viewer can also display documents containing QuickTime content, open AppleScript-basedautomations,retrieveupdatedhelpcontentfromtheInternet,andprovidecontext-sensitive assistance.

Users can access Apple Help by launching the Help Viewer application but they will more commonly access it from your application, in one of three ways:

■The Help menu. The Help menu is the far-right item in the application region of the menu bar. When you register your help book with Help Viewer, the first item in the Help menu is the system-provided Spotlight For Help search field. The second item in the menu should be ApplicationName Help, which opens Help Viewer to the first page of your help content. For more information on the Help menu, see “The Help Menu” (page 183).

■Help buttons. When necessary, you can use a Help button 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.

■From a contextual menu item. If contextually appropriate help content is available for the 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.

See AppleHelpProgrammingGuide for more information on writing Apple Help content and providing it with your application.

Help Tags

Helptags enable your application to provide basic help information for its interface elements without forcing the user to leave the primary interface.

Help tags are short messages that appear when the user leaves the mouse pointer hovering over an interface element for a few seconds (see Figure 6-12 for an example of a help tag). When the pointer leaves the object, the tag vanishes. If the mouse pointer is not moved, the operating system hides the help tag after about 10 seconds.

80	User Assistance

2008-06-09 | © 1992, 2001-2003, 2008 Apple Inc. All Rights Reserved.

C H A P T E R 6

Using Mac OS X Technologies

Figure 6-12

A help tag

The text of a help tag should briefly describe what an interface element does. If you find that you need more than a few words to describe the function of a control, you might want to reconsider the design of your application’s user interface.

Define help tags in Interface Builder, where they are called tooltips. Here are some guidelines to help you create effective help tag messages.

■Use the fewest words possible. Try to keep your tags to a maximum of 60 to 75 characters. Because help tags are always on, it is important to keep your tag text unobtrusive—that is, short—and useful. A tag should present only one concept and that concept should be directly related to the interface element. Localization can lengthen the text by 20 to 30 percent, which is another good reason to keep the tag short.

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

■Describe only the element the mouse pointer hovers over.

■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.

■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.

■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 interface element accomplishes, you may help the user understand the current state of the control even if the tag is applicable to all situations.

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

Describe what the user will accomplish by using the control. For example, “Add or remove a language from your list” or “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.

User Assistance

81

2008-06-09 | © 1992, 2001-2003, 2008 Apple Inc. All Rights Reserved.

C H A P T E R 6

Using Mac OS X Technologies

82	User Assistance

2008-06-09 | © 1992, 2001-2003, 2008 Apple Inc. All Rights Reserved.