The Help Viewer Window

Users typically launch Help Viewer by selecting the application help item from the Help menu, described further in How Users Access Your Help. When Help Viewer launches, it brings up the window shown in Figure 1-1, displaying help for the application from which the user requested assistance. In Figure 1-1, the Help Viewer window displays the system help book, Mac Help.

By default, there are three user interface elements in the toolbar at the top of the Help Viewer window: the Back button, the Help Center button, and the search field. The Back button on the left side of the toolbar allows users to navigate back to previously visited help pages; users can also view their navigation history and revisit pages using the Go menu. The Help Center button opens and closes the Help Center drawer; the Help Center is described further in The Help Center. The search field allows users to search all available help on the system.

Users can customize the Help Viewer toolbar by choosing the Customize Toolbar item from the View menu. Users can add additional controls, such as a Forward button, Print button, or font size buttons, or choose a different view for the toolbar.

Searching in Help Viewer

One of the primary advantages of Help Viewer for viewing online help is its ability to quickly and accurately search an installed set of help content. Users often arrive at online help with an idea of what they want to accomplish; help should allow them to get the information they need as quickly as possible and get on with their tasks. Especially for large help systems, searching is often the most efficient and effective way for users to obtain help.

The text entry field at the right side of the Help Viewer window’s toolbar allows users to search the available help content on the system. Users enter the term or concept for which they want to obtain help into the text field. They can also enter a question. Figure 1-2 shows a question entered in the text field of the Help Viewer window.

When the user presses Return, Help Viewer searches the help books installed on the system for the relevant term or terms. Figure 1-3 shows the search results returned by Help Viewer in response to the question entered in Figure 1-2.

Help Viewer displays the titles of each relevant help topic in a table of search results, along with the help book in which that topic is found. Search results are ranked by relevance, with the topmost hits having the highest relevance. When the user selects a topic from the search results, the bottom frame of the Help Viewer window displays a summary of the help topic, if available. The user can view the selected topic by double-clicking the topic in the search results table or by following the link in the bottom frame of the Help Viewer window. Figure 1-4 shows the summary for a help topic returned as a search result for the query entered in Figure 1-2.

The Help Center

The Help Center, displayed in a drawer, lists all of the help books currently installed on the user’s system. With the Help Center, users can easily access and browse all of the help available to them. Figure 1-5 shows the Help Center.

The Help Center is visible by default when Help Viewer is launched, but users can hide and show the Help Center using the button in the Help Viewer toolbar. Because the Help Center is available to the user at any time, no matter what help book they are currently viewing, users can conveniently switch between help books without switching applications. When the user selects a help book in the Help Center, Help Viewer loads that help book.

The Help Menu

Users access your application’s help book and other help resources through the Help menu, the rightmost menu in the application region of the menu bar. Although your application may also provide additional means of obtaining help, such as contextual menu items or help buttons, the Help menu is the most obvious means of obtaining assistance for the majority of users. Because the Help menu is easily visible, remains in a consistent location, and is always accessible, it is the first place users go when they have a question. Help menu items are not context-sensitive.

Figure 1-6 shows the Help menu in iTunes.

The Help menu is supplied by the system. The first item in the Help menu should be titled ApplicationName Help, where ApplicationName is the name of your software product. When the user chooses this item from the menu, you should open Help Viewer to the first page of your application’s primary help book. If you have registered your help book, the system not only creates the Help menu and the application help menu item for you, it also handles the choice of the application help menu item by opening Help Viewer to your application’s registered help book.

In addition to your application’s primary help book, you may want to include items for other help resources, such as links to support or customer service websites or tutorials, in the Help menu.

Help Buttons

A help button is a small round button displaying the standard help icon—a question mark.

When contextually relevant help is available, you can use help buttons in the lower-left corner of a window or dialog to take users directly to the pertinent information. For example, you can use a help button in a Preferences dialog to take users directly to information about setting preferences for your application.

Figure 1-7 shows a typical help button, in the lower-left corner of an AppleWorks dialog.

You should use help buttons only when contextually relevant help exists for the current window or dialog. Help buttons should allow users to obtain assistance for the task at hand without searching through your help book.

When the user clicks the help button, your application should load the relevant help topic in Help Viewer, using the Apple Help functions AHLookupAnchor or AHGotoPage. See The Apple Help Application Programming Interface for more information on using these functions.

Help in Contextual Menus

You can also provide context-specific user assistance through contextual menu items. Contextual menus are displayed when the user Control-clicks an object in an application’s user interface. If help pertaining to that object exists—for example, a a description of how to use that user interface element—the first item in the contextual menu should be a help item. Figure 1-8 shows a contextual menu containing a Help item.

If the user selects the help item from the menu, you should use the function AHLookupAnchor or AHGotoPage to load the relevant page of your help book in Help Viewer. To learn more about using Apple Help functions to access your help book, refer to Opening Your Help Book in Help Viewer.

Help-Specific Meta Tags

Help Viewer recognizes a set of properties for the standard HTML <META> element, which you can use to control how your help book appears in the Help Center and in search results. You can also use these meta tags to control how your help is indexed. Authoring User Help describes many of these meta tags and how you can use them. For a complete list of the help-specific meta information recognized by Help Viewer, see Table A-1.

Help URLs

There are several URLs, using the Help Viewer help: protocol, that you can use in your help book to create links to additional help content. You use the standard <A HREF> syntax for a source link with these help URLs. Although you can use help URLs to link to HTML help pages, their main advantage is that they allow you to create hyperlinks that, when clicked, initiate searches in Help Viewer, run AppleScript scripts, and perform anchor lookup.

The help URLs are described in more detail in the section Adding Specialized Content to Your Help Book. For a full listing of the supported help URLs, see Table B-1.

Apple Help Segments

Help Viewer also recognizes certain HTML comments that you can use to split an HTML file in your help book into subsections, called segments. Segments can be returned as individual hits in a search, each with its own description, title, and search keywords. You may find it useful to use segments if you have a particularly large help book and wish to reduce the file count without loading too much help content into a single help page. Creating Segments in Help Pages describes segments in more detail. See Table C-1 for a complete list of the comments denoting segments.