Ideally, people can figure out how to use your app without a guide. However, even in a highly intuitive app, users sometimes need help learning advanced and secondary features. When called for, your app can offer assistance in the form of 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.

Avoid restricting user actions. Unless you’re creating a children’s app in which it can be appropriate to restrict the user’s scope of action, let people do what they want without unnecessary interference. For related guidance, see Onboarding and Providing User Feedback.

Help Tags (Tooltips)

Help tags, often referred to as tooltips, succinctly describe how to use controls without shifting people’s focus away from the primary interface. Help tags appear when the user positions the pointer over a control for a few seconds. For example, Finder displays a help tag that describes the behavior of the Share toolbar button. A help tag remains visible for 10 seconds, or until the pointer moves away from the control.

Describe only the control that’s directly beneath the pointer. People expect a help tag to describe what they can do with the control. They don’t expect to learn about other controls or how to perform a larger task.

Add help tags to app-specific controls. Don’t provide help tags for window resize controls, scrollers, or other system-provided controls.

A screenshot of the help tag that appears when positioning the pointer over the close tab button in Safari.

Focus on the action a control initiates. A good way to stay focused on the action is to begin the tag with a verb. For example, “Restore default settings” or “Add or remove a language from the list.”

Use the fewest words possible. As much as possible, limit tags to a maximum of 60 to 75 characters. If you need more text to describe a control, your interface design might be overly complicated. You can also omit articles to reduce the length of a tag. Note that localization can lengthen text by 20 to 30 percent, which is another good reason to keep tags short.

In general, don’t reference a tag’s corresponding control. A help tag appears directly over the control, which usually provides sufficient context. If you must refer to a control by name, do so consistently throughout all of your documentation. Avoid defining a tag that does nothing but repeat the name of a control.

Use sentence fragments with sentence-style capitalization. This style emphasizes brevity and tends to be more friendly, which connects well with users in need of assistance. If the tag text must form a complete sentence, use appropriate ending punctuation.

Consider offering context-sensitive help tags. You could provide different text for different control states, for example.

Use the term help tag instead of tooltip when referring to help tags in your app or user documentation. The term tooltip is reserved for use in developer content. The term help tag refers to the instructional text that appears when the pointer hovers over an interface element. See Apple Style Guide.

Apple Help

Apple Help lets your app provide detailed, task-oriented documentation through Help Viewer, a browser-like app designed for displaying and searching help topics. Help topics can include text, images, videos, and context-sensitive content that’s stored locally or remotely. Apple Help is accessed using an app’s Help menu, from contextual menus, and by clicking Help buttons in the app’s interface. While the Help menu (which includes an integrated search field) provides access to all of an app’s help documentation, help buttons and contextual menus can be mapped directly to specific topics.

Safari’s Help window.

Provide task-based help. People look for help when they can’t figure out how to accomplish a goal. Although users sometimes want a quick reference guide, they’re more likely to seek help with specific tasks. In general, describe control usage in the context of accomplishing a task.

Use the system-provided Help Viewer app. Help Viewer is familiar and provides a consistent browsing experience across the system. When people look for 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 a help viewing mechanism that differs from the one they use in all their other apps.

Only display a Help button in a window when contextually relevant help is available. Help content is always accessible from the Help menu, so it’s unnecessary for every one of your app’s windows to include a Help button.

For related guidance, see Help Menu. For developer guidance, see NSHelpManager.