Guides and Sample Code

Developer

macOS Human Interface Guidelines

iBooks

User Assistance

macOS supports two user help features: Help tags and Apple Help. 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 task.

For the best user experience, don’t create a custom help viewer. When users refer to help, it’s usually because they are having difficulty accomplishing a task, which means they might be frustrated. This isn’t 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 apps on their computer.

Using Apple Help, you can display HTML files in Help Viewer, a browser-like app designed for displaying and searching help documents. Help Viewer can also display documents containing QuickTime content, open AppleScript-based automations, retrieve updated help content from the Internet, and provide context-sensitive assistance.

Although users can access Apple Help by launching the Help Viewer app, they will more commonly access it from your app, in one of the following three ways:

  • The Help menu. The Help menu is the last app menu item in the menu bar (in left-to-right systems, the Help menu is on the right). 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 AppName Help, which opens Help Viewer to the first page of your help content. For more information on the Help menu, see The Help Menu.

  • Help buttons. A Help button provides easy access to specific sections of your help book. When a user clicks a Help button in your UI, you send to Help Viewer either a search term or an anchor lookup.

  • From a contextual menu item. If contextually appropriate help content is available for the object the user has Control-clicked, the first item in the contextual menu is Help. As with Help buttons, this menu item can send either a search term or an anchor lookup to Help Viewer.

Only display a Help button in a window when there is contextually relevant help available. It’s not necessary for every dialog and window in your app to include a Help button. Because the Help menu is available, users always have another way to access your help content. To learn how to write Apple Help content and provide it with your app, see Apple Help Programming Guide.

Help tags allow you to provide basic help information for UI elements in your app without requiring users to shift their focus away from the primary interface.

Help tags appear when the user allows the pointer to rest on a UI element for a few seconds. When the pointer leaves the object, the tag vanishes. If the pointer isn’t moved, the system hides the help tag after about 10 seconds. For example, the Finder displays a help tag that describes the behavior of the Share toolbar control.

image: ../Art/help_tag_2x.png

Note that help tags look similar to expansion tooltips, but they aren’t the same. An expansion tooltip can appear when users position the pointer over truncated text in a table, outline, or browser view’s cell. For example, when a filename is too long to display without truncation in a Finder window, an expansion tooltip displays the complete text. (To learn more about enabling expansion tooltips in your app, see allowsExpansionToolTips.)

image: ../Art/expansion_tag_2x.png

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 app’s user interface.

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

In general, don’t name the interface element in the tag. Because a help tag is specific to a UI element, it shouldn’t be necessary to refer to it by name, unless the name helps the user and isn’t available onscreen. If you do need to refer to an element by name, make sure you use the same name throughout all of your documentation.

Describe only the element that the pointer is resting on. Users expect a help tag to describe what they can do with the control; they don’t expect to read about other controls or about how to perform a larger task.

Describe controls that are unique to your app. Don’t provide help tags that describe window resize controls, scrollers, or other system-provided controls.

Focus on the action users can perform using the control. A good way to stay focused on the action is to begin the tag with a verb, for example, “Restores default settings” or “Add or remove a language from the list”.

Use the fewest words possible. Help tags are always on, so it’s important to keep your tag text unobtrusive—that is, short—and useful. As much as possible, keep tag text to a maximum of 60 to 75 characters. A tag should present only one concept and that concept should be directly related to the interface element. You can also omit articles to limit the length of the tag. Note that localization can lengthen the text by 20 to 30 percent, which is another good reason to keep the tag short.

Use sentence-style capitalization. Sentence-style capitalization tends to appear more friendly and less formal to users (to learn more about this capitalization style, see Use the Right Capitalization Style in Labels and Text).

In general, use a sentence fragment. A sentence fragment emphasizes the brevity of the help tag’s message. If the tag text must form a complete sentence, end it with the appropriate punctuation.

Consider creating contextually sensitive help tags. You can provide different text for different states a control can have, or you can provide the same text for all states. When you describe what the interface element accomplishes, you help the user understand the current state of the control even if the tag isn’t applicable to all situations.