No matter how intuitive a user interface for an application may seem to the developer, it’s likely some people will need information about using it. To make a complete application, you should provide user help.
Apple’s philosophy of help is that users look at it with a specific goal in mind. In other words, users turn to help when they know what they want to do in the application but aren’t sure how to do it. The application’s help should get users back to their task as quickly as possible. When users open help, chances are that they are already somewhat frustrated and impatient; well-designed help plays a significant part in a user’s overall experience with your application.
In Carbon, you can provide two types of help in your application: help books and help tags. A help book provides onscreen documentation about how to perform tasks or troubleshoot problems. A help book is a collection of HTML files that users view in Help Viewer, a simple browser that can open automatically from your application. A help tag provides a brief description of something in the user interface. A help tag appears when the user hovers the mouse pointer over the item in the interface.
To work with help books and integrate them into your application, you use Apple Help, a technology that includes definitions of HTML elements and programming interfaces. To add simple, text-only help tags to your application, you can use Interface Builder. If you want to provide fancier help tags, including graphics or QuickTime movies, for example, use the Carbon Help Manager.
In this chapter you’ll:
Learn about help books and what type of content is appropriate for them
Look at the basic mechanics for producing searchable help books
Learn how help tags work and when and how to use them
Add a help book to Moon Travel Planner and register it
Add a help tag to Moon Travel Planner
Help books provide the type of content that probably comes to mind when you think about online help for an application. The information in a help book should answer questions that users have about how to accomplish a task or how to fix something that went wrong. Earlier in this book, you learned how to access developer documents through the Project Builder Help menu. These documents are examples of help books that you view in Help Viewer. Figure 12.1 shows a page in Mac Help, another example of a help book provided by Apple. (Mac Help contains information to answer questions users might have about using the Finder, System Preferences, and other parts of Mac OS X that users interact with.)
A user can open your help book in Help Viewer by choosing a menu item in the Help menu or by clicking a Help button that’s always visible in the application interface. Once your help book is open, a user can type a query or browse a table of contents to get to pertinent information. To open your help book directly to a relevant page, you can also add Help buttons or contextual menus in appropriate places in your user interface.
Help tags provide a type of help that’s simpler than that of help books; help tags contain hints about how to use controls and other elements in the user interface. Sometimes a brief description of a control is all a user needs to proceed with a task. Figure 12.2 shows a help tag in the Interface Builder palettes window. By looking at the brief description of each palette, you could quickly get an idea of what elements are in each palette.
You can create content for help books using any authoring tool that generates HTML 3.2 files. You should, however, preview all pages in Help Viewer to ensure that your HTML content functions as you intend when it is opened in Help Viewer.
Place all content for a help book in a help folder for your application. A help book typically consists of an HTML file specifying a title page for the book and a separate HTML file for all other pages of the book. Such files are typically organized into subfolders.
You can create a simple help book, or you can divide your help book into sections called “chapters.” Your help book automatically becomes accessible to users via the Help Center, an Apple-provided location that allows users to easily browse and search all help on their computer. If your help book is organized into chapters, Apple Help uses their titles to create a table of contents for your book. Apple Help enables you to open applications, QuickTime movies, and other scriptable items from within the HTML content, and it allows you to index your content and make it searchable.
Here are a few suggestions to keep in mind as you write your help books. For more information about Apple’s philosophy for help, see Inside Mac OS X: Aqua Human Interface Guidelines in Carbon Help (available in the Project Builder Help menu).
Focus on actual user tasks and troubleshooting. To come up with relevant tasks, imagine people using your application and asking “How do I . . .?” or “Why can’t I . . .?”.
Don’t document obvious tasks or interface elements. The more topics your help contains, the harder it is for users to find what they’re looking for. Focus on behaviors that truly need explanation.
Be as concise as possible. Remember that the user wants to be doing his or her work, not reading help text.
Be judicious about including illustrations of the interface. Users may confuse art with the actual interface, and too much art can be distracting. When you do use art, make sure that it truly enhances the help content, and make it obvious that illustrations are not interactive.
To take full advantage of Apple Help and Help Viewer and to make your help book as useful as possible, there are certain basic elements that you may want to include. The following sections describe several of the most important help book components.
An anchor is a label that you create with the HTML tag <A
NAME>. Your application must use at least one anchor in order
for the Help Viewer to be able to locate the application’s help.
You can also use this HTML tag to label basic tasks or information
likely to be looked up frequently. You can provide quick access
to information that you label with an anchor yourself by calling
the Apple Help function AHLookupAnchor,
and you can include anchors in your help’s index. (For more information,
see Section 12.1.1.3.)
The following is an example of an anchor:
<A NAME="Creating a Cartoon Character"></A>
You can divide a single HTML file into smaller sections so that each segment is returned as a separate “hit” result when the user searches your help book. Segments differ from chapters. Segments simply focus the results of user searches on your book. An example of the markup for a segment is shown in Example 12.1.
Example 12-1. Dividing an HTML File into Segments
<!--AppleSegStart ="Creating a Cartoon Character"--> <A NAME="Choosing an Expression"></A> The help content goes here... <!--AppleSegEnd-->
Note that this example also includes an anchor. Also note
that every AppleSegStart tag must
have an AppleSegEnd tag.
You can also add descriptions to your help content. These descriptions are displayed with Help Viewer search results, assisting users with determining which topic is most relevant to them. There are two ways to provide descriptions for your help content. You can provide an abstract for an HTML file as a whole, or you can provide descriptions for individual segments within an HTML file.
To create a description for one complete help page you would use this tag in the HTML file for that page:
<META NAME="DESCRIPTION" CONTENT="This section describes the tools you can use to create a cartoon character.">
To create a description for a segment within a help page,
you would use the AppleSegDescription tag.
A description for the segment on choosing an expression, for example,
added to the segment in the previous listing, is shown in Example 12.2.
Example 12-2. Adding a Description (Search Result Abstract) to an HTML Segment
<!--AppleSegStart ="Creating a Cartoon Character"--> <A NAME="Choosing an Expression"></A> <!--AppleSegDescription="This section describes the Expression palette and shows how you can assign an expression to a cartoon character."--> The help content goes here... <!--AppleSegEnd-->
Using anchors, segments, and descriptions makes your help content searchable on a basic level. In many cases, however, users don’t know the exact spelling or terminology to use for a query in Help Viewer. That’s where keywords come in; keywords enable you to add common misspellings, as well as synonyms for concepts and sections in your HTML help content, so that a user who enters one of these keywords can obtain relevant search results. For example, a user entering the query “How do I give a cartoon character an expression?” would certainly arrive at the appropriate help content. But a user who types “How do I make Mr. Grump have a happy face?” would get no search results. To add the keywords “happy” and “face” to the help content, you would add the following to our HTML content:
<!--AppleKeywords="happy, face"-->
The following tag would add keywords to the entire HTML file:
<META NAME="KEYWORDS" CONTENT="happy, face">
Help Viewer uses the Sherlock search engine to provide fast, full-text searching of help books. To make your help content searchable in Help Viewer, you must use the Apple Help Indexing Tool. The indexing tool is available in the Apple Help Software Developer’s Kit (SDK) (see Appendix A for information on getting SDKs from Apple).
Before you create an index, make sure your help files are in their final folder locations. The index file stores relative path information, so moving content files after indexing invalidates the index file.
If you put anchors in your index, you must tell the tool to include them before you create the index. To do so, open the Indexing Tool, choose Preferences from the Edit menu, and select the Anchor Indexing checkbox.
To create an index file, simply drag the folder containing your help content onto the Apple Help Indexing Tool. The Indexing Tool scans the folder and creates a file inside the folder you dropped on the tool. This index file must remain in the folder for the index to work correctly.
To learn more about creating help books, see the Apple Help documentation in Carbon Help (available in the Project Builder Help menu).
Whereas a help book allows you to provide detailed help for your application, help tags provide a mechanism for offering users short hints and tips about your application as they move through the application’s interface.
A help tag—a small rectangle that displays text—appears when the user hovers the mouse pointer over an interface element. Help tags are useful for providing brief descriptions of controls, such as a button that displays an icon but no text. (See Figure 12.2 for an example of a help tag for a control.)
If the pointer hovers for a specified length of time over an item that has a help tag, the Carbon Help Manager displays the text in a help tag. When the user moves the pointer off the item, the Carbon Help Manager removes the help tag from the screen.
The easiest way to add help tags is to use Interface Builder. If an interface element supports help tags, you can specify the text for it in its Info window in Interface Builder; you don’t have to write any code. Creating help tags in this way will be sufficient for most applications. You’ll see how to do that later, in Section 12.2.
You can also create help tags with the Carbon Help Manager.
You’ll need to write code using Carbon Help Manager functions,
such as HMSetControlHelpContent, HMSetWindowHelpContent,
and HMSetMenuItemHelpContent to
associate help tag content with an interface element. If you prefer,
you can use the Carbon Help Manager to associate a callback function
with the interface element for which you want to provide a help
tag. The Carbon Help Manager calls this function to display the
help text. If you use this method, you are also responsible for
disposing of the help tag content when the tag is removed from the
screen. If you want more information, see the Carbon Help Manager
documentation in Carbon Help (available in the Project Builder Help
menu).
Use help tags to help users determine the function of interface elements. Note that help tags should be state-independent: a help tag for an item always displays the same text, even when the item is in an unavailable state. For example, let’s say the Forward button in a mail program has this help tag: “Send the selected message to someone else.” The word “selected” gives a clue as to why the button may be dimmed (because the user hasn’t selected a message yet).
When you write help tags, keep the following guidelines in mind:
Keep it short. The longer the text, the larger the tag; the larger the tag, the more that it interferes with your application’s interface. Help tags are useful for providing additional hints, but they are not suitable for providing comprehensive instructions about the operation of your application; that type of content should be provided through help books. Keep each help tag to a maximum of 75 characters.
Don’t tell users something they already know. Repeating already visible information simply clutters the screen. If the item has an onscreen label, for example, you don’t need to repeat the item’s name in the help tag. Don’t create a tag for a “Send” button that says “Sends mail.”
Make it relevant. The help tag text should tell users what they want to know most about the item, which is usually the task they can perform by using it.
Don’t get tag happy. You don’t need to label everything on the screen. Don’t create tags for standard operating system elements such as windows, scroll bars, title bars, and menus. For instance, create a tag for a window if the purpose of the window might not be clear (a tool palette, for example); don’t create a tag simply to say that it is a window. Assume that anyone using your application already knows interface basics.