C H A P T E R 1 4

User Help and Assistants

Mac OS X supports two user help components: Apple Help and help tags. CarbonLib-based applications can also use these facilities back to Mac OS 8.6.

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

Help tags, which replace the help balloons introduced in System 7, give your application the ability to identify its interface elements and provide basic help information without forcing the user to leave the primary interface.

Apple’s Philosophy of Help

When users refer to help, it is usually because they are having difficulty accomplishing a task—they know what they want to do, but not how to accomplish it. When faced with an impasse, most users first try to figure it out for themselves by exploring and experimenting with the interface. If that fails, they ask someone else for assistance; if no one is available, they may consult the onscreen help.

Users come to help with a specific goal in mind, bringing their cumulative Macintosh experience and the recent and cumulative experience of using the product. In all likelihood, they are somewhat impatient and frustrated at having failed to figure out how to accomplish their goal.

C H A P T E R 1 4

User Help and Assistants

To assist users in quickly locating their information and getting back to work, onscreen help should do the following:

■Focus on real-world user tasks.

■Get to the point quickly, so users can return to work.

■Be organized by task, not the layout or functionality of the software.

In large help systems, searching is often the most efficient way to locate a particular topic, particularly when users have turned to help with a specific idea about what they are trying to accomplish. To facilitate usable search results, do the following:

■Cover one topic per page, to avoid burying some tasks.

■Title the page descriptively, using words that relate to real-world goals.

■Use Apple Help keywords to ensure synonyms and common misspellings get appropriate search results.

■Write steps and descriptions using words that appear in the interface.

Write your help so that users can quickly find the steps on the page and can follow the steps without having to repeatedly switch between the product and the Help Viewer.

■Don’t repeat notes and warnings enforced by the interface. For example, if you have to click OK to confirm a setting, don’t describe it in the steps—it will be apparent as the users follow the instructions.

■Tailor descriptions to the probable experience of users. For example, a user who wants to adjust kerning is likely to be already familiar with selecting a typeface and font size. A user who looks for help with basics such as opening a document may require more detailed instructions.

■Automate common tasks using AppleScript. For example, if a task requires opening a preferences pane, provide an automation that opens it for users. If you can automate the entire task, do so.

■Emphasize trouble identification and resolution. Users might already know how to accomplish a task but turn to help because of a condition or requirement they can’t identify. If a step or task might be impossible because of an error condition, remind users to check for it early in your instructions.

236Apple’s Philosophy of Help

Apple Computer, Inc. June 2002

C H A P T E R 1 4

User Help and Assistants

Help Viewer

Use Help Viewer to display onscreen documentation. Help Viewer displays HTML documents, fully supports QuickTime media, provides full-text searching of help with relevancy-ranked results, and provides for task automation using AppleScript. Additionally, Help Viewer allows you to integrate Internet-based help files, permitting you to update and improve your instructions as often as necessary.

The collection of your HTML help files is called a help book. When you use Help Viewer, your help book automatically becomes accessible via the Help Center, an Apple-provided location that allows users to easily browse and search all of the help available on their system.

A help book should be the primary location for your application’s user instructions and information. If you provide other instructional resources, such as full-screen tutorials or “how to” articles on your website, include hyperlinks to them in your help book. Users can find these other resources by searching or browsing the help, reinforcing its usefulness as a reference.

Providing Access to Help

Users can access the help system in three ways:

■The Help menu. The Help menu is the far-right item in the application region of the menu bar. The first item in the Help menu should be Application Name Help, which should open Help Viewer to the first page of your help content. It’s best to have only one item in the Help menu, but if you want to add additional items that are distinct from your help content, such as tutorials or website links, they should appear below the Application Name Help item.

Apple Computer, Inc. June 2002