Giving Users Help with Apple Guide

JOHN POWERS

A positive user experience means getting the task done with a minimum of hassle. But as applications engage in the features race, their complexity increases as well, leading to increased user frustration. One solution is to add a powerful help system that can guide the user through a task. The new Apple Guide system makes this chore easier than you might think.

Someone has decided that your application needs help. Maybe it's a little heavy on the features, and Marketing is afraid that the user will be overwhelmed. Perhaps your user studies have shown that users can really benefit from some coaching when learning your interface. Or the finance experts have figured out that you can save a lot of money on printing and user support costs by putting help on the screen rather than in printed manuals. And yesterday the CEO declared that your product must win a gold medal in customer satisfaction.

It can be done.

This article tells you how to add Apple Guide, a new kind of help system, to your application with a pain and suffering level that you can control, ranging from almost nothing to only a tingle.

The article doesn't tell you what help your application should provide; that's up to your software designer, technical writer, instructional designer, interface designer, and whoever else likes to stir the design pot. Once you've decided what help you want and the technical writer has written it using the Apple Guide authoring tool, you integrate it. That's where this article -- and this issue's CD, which contains a sample program with Apple Guide integrated -- comes in.

WHAT IS APPLE GUIDE?

Apple Guide is a new kind of help system that acts as an interactive, task-oriented guide and will be available to all applications systemwide as of System 7.5. Apple Guideis based on more than two years of research on people's need for help while usingtheir computers. Several key findings of this research underlie the Apple Guide design:

• Users are task-oriented.
• Users seek help when they're frustrated doing a task.
• Help should be an interactive guide to accomplishing a task, not a static document.

The paradigm is simple:

1. The user has a task to accomplish.
2. The user becomes frustrated when an obstacle prevents completion of the task.
3. The user asks for help.

Traditional help requires users to go to a printed or on-screen document to identify the problem in the context of the documentation. This in itself can become a frustration. Users would rather have someone (or something) guide them through the obstacle. That's what Apple Guide does: it acts as an interactive, task-oriented guide.

When users ask for help, the first thing they see is theaccess window , which provides three ways of selecting the help topic. Once the user selects the help topic, the access window is replaced by the presentation window , which presents the help topic as a series of panels containing text, graphics, QuickTime movies, and controls. (Note that in an application in which Apple Guide has been fully integrated, the help topic can be preselected for the user based on context -- more on this later.) To experience Apple Guide for yourself, try out the application called MoGuide on this issue's CD.

Apple Guide is implemented as a system extension (see "What Systemwide Help Means" for some ramifications of this) that uses a guide database file to drive its interaction with the user, as depicted in Figure 1. The database file, written using the Apple Guide authoring tool, contains multimedia help content and instructions on how to interact with the user. The delivery engine is in the system extension, which contains two components: a stay-resident portion and a launch-as-needed application portion. With a RAM footprint of less than 20K, the stay-resident portion installs patches at startup time, manages the Help menu (the one labeled with a question mark in a balloon), and starts up Apple Guide from the Help menu. The applicationportion is loaded and run when help is being delivered; with a RAM footprint of 400K,it's launched as a faceless background application in its own heap. The Apple Guide system extension and several guide databases will be provided as part of System 7.5.

Figure 1. How Apple Guide works

TO INTEGRATE OR NOT TO INTEGRATE?

You can put Apple Guide to work for you whether or not you decide to integrate it into your application. However, as in life, the level of pain you choose determines the amount of gain.

The easiest way to add Apple Guide to an application is to place an Apple Guide database file in the same folder as the application. No coding changes are necessary; the integration is automatic. The Apple Guide extension adds the database to the application's Help menu and launches the database when the user chooses it.

Here's what Apple Guide delivers without any changes to your application:

• help initiated from the Help menu
• interactive delivery of multimedia help content
• the ability to mark static interface objects, or dynamic interface objects identified using the Object Support Library (OSL), to draw the user's attention to them
• elementary to intermediate context sensitivity

This is a lot of help in itself. But if you want more control over Apple Guide, you'll need to make code changes in your application. Here's what those changes can add:

• information about where the user is in the help system
• more direct control over what help the user receives and responsiveness to the user's context
• help initiated from any control -- including buttons, lists, and special keys -- and from application menus
• guide databases with your own creator, type, and document icons
• the ability to use databases located in a folder separate from the application

If you want the gain and you're ready for the (slight) pain, read on.

To communicate with Apple Guide from your application, you use standard, trap-based function calls. The function calls enable your application to get information about Apple Guide, start up Apple Guide, respond to Apple Guide, modify help content, and quit Apple Guide. I'll explain how to do each of these in the sections that follow. You might want to examine the source code for the sample program MoGuide on this issue's CD to see the function calls used in context. Then you can try integrating Apple Guide into your own application.

GETTING INFORMATION ABOUT APPLE GUIDE

Your application can find out a number of different things about Apple Guide: whether it's installed, what its status is, whether an Apple Guide database is available, the number and characteristics of guide databases available, and whether your own guide database is open.

IS APPLE GUIDE INSTALLED?
Before you do anything with the Apple Guide extension, you need to determine whether it's installed. The following code shows how:

long    result=0;
OSErr   err = Gestalt(gestaltHelpMgrAttr, &result);
if (err==noErr && (result & (1 << gestaltAppleGuidePresent)))
    ;   // Apple Guide is available.
else
    ;   // Apple Guide is not available.

WHAT'S THE STATUS OF APPLE GUIDE?
Once you've determined that Apple Guide is installed, you can get more information about its state -- for example, is it active (displaying a help window)? If it is, which help window is being displayed? The latter information can be saved and used to restart users at the point where they left the help system.

The AGGetStatus function returns whether Apple Guide is active (kAGIsActive), sleeping (kAGIsSleeping), or not running (kAGIsNotRunning). In the active state, help is being provided (a guide database is open). In the sleeping state, the Apple Guide background application is loaded and running, but no help is being provided (no guide database is open). In the not-running state, the application portion of Apple Guide isn't loaded or running.

If Apple Guide is active, you can further determine whether the access window or the presentation window is showing. For example:

if (AGGetActiveWindowKind()==kAGAccessWindow)
    ;// Apple Guide access window is showing.
else if (AGGetActiveWindowKind()==kAGPresentationWindow)
    ;// Apple Guide presentation (topic) window is showing.
else
    ;// No window is showing; Apple Guide is sleeping or not running.

Be sure you've determined that Apple Guide is installed before invoking AGGetStatus or any other Apple Guide function. Otherwise, if Apple Guide isn't present, you'll get an unimplemented trap error.

IS AN APPLE GUIDE DATABASE AVAILABLE?
You can find out whether an Apple Guide database is available to the current (frontmost) application, and furthermore, whether a specific type of guide database is available. (There are two file types and five database types, classified according to the type of help information they contain; see "About Apple Guide Database Files" for a rundown of the types.)

The AGGetAvailableDBTypes function returns bits set to correspond to the various types of guide databases available to (in the same folder as) the frontmost application.

enum AGDBTypeBit        // To test against AGGetAvailableDBTypes
{
    kAGDBTypeBitAny =           0x00000001,
    kAGDBTypeBitHelp =          0x00000002,
    kAGDBTypeBitTutorial =      0x00000004,
    kAGDBTypeBitShortcuts =     0x00000008,
    kAGDBTypeBitAbout =         0x00000010,
    kAGDBTypeBitOther =         0x00000080
};

The kAGDBTypeBitAny bit will be true if the application has any Apple Guide database file available. Thus, the following statement will test whether any guide database is available:

if (AGGetAvailableDBTypes() & kAGDBTypeBitAny)
    ;   // Some kind of database is available

You can simlarly use the other constants to test the availability of specific types of Apple Guide databases.

HOW MANY AND WHICH GUIDE DATABASES ARE AVAILABLE?
The tests described in the preceding section apply only to guide database files or their aliases in the same folder as the application. You can also find files outside the application's folder, by using the AGFile library that's included on this issue's CD. This library doesn't use or require the Apple Guide system extension and offers access to information about Apple Guide database files. With the AGFile library, you can count and find guide databases of specific file and database types. Once you've found a database, you can get information about it. For example, the following code counts the number of main guide database files (those that aren't mix-in files) of type kAGFileDBTypeHelp in a specified volume and directory:

AGFileCountTypeguideFileCount;
AGFileDBType databaseType=kAGFileDBTypeHelp;
Boolean wantMixin=false;

guideFileCount = AGFileGetDBCount(vRefNum, dirID, databaseType,
    wantMixin);

You can get the FSSpec for a particular type of Apple Guide database file in a specified volume and directory as follows:

AGFileCountTypeguideFileCount;
AGFileDBType databaseType=kAGFileDBTypeOther;
Boolean wantMixin=false;
short dbIndex=1;
FSSpec dbSpec;

err = AGFileGetIndDB(vRefNum, dirID, databaseType, wantMixin,
        dbIndex, &dbSpec);

The AGFileGetIndDB call will return noErr and the FSSpec for the database file if it's present. Increment dbIndex to find additional guide databases of the same type.

Listing 1 shows how to accumulate a list of FSSpecs for all the guide databases in a specified volume and directory.

Listing 1. Accumulating FSSpecs for guide databases
AGFileCountType     guideFileCount;
AGFileDBType        databaseType=kAGFileDBTypeAny;
Boolean             wantMixin=false;
FSSpec              dbSpec;
Handle              hFileList;

// See how many guide files are available.
guideFileCount = AGFileGetDBCount(vRefNum, dirID, databaseType, 
    wantMixin);
if (guideFileCount>0) {
    // Create a new list of file FSSpecs.
    hFileList = NewHandle(guideFileCount * sizeof(FSSpec));
    if (hFileList!=nil) {
        // Get each file and add to list.
        for (short i=1; i<=guideFileCount; i++) {
            if (AGFileGetIndDB(vRefNum, dirID, databaseType,
                    wantMixin, i, &dbSpec)==noErr) {
                ((FSSpec*)(*hFileList))[i-1] = dbSpec;
            }   // if (...
        }   // for (short...
    }   // if (hFileList...

Listing 1. Accumulating FSSpecs for guide databases

Once you have the FSSpec for a database file, you can ask for more information. For example, the following code can be used to get the version and menu item name for a database:

AGFileMajorRevType  majorRev;
AGFileMinorRevType  minorRev;
Str255              menuName;

AGFileGetDBVersion(&fileSpec, &majorRev, &minorRev);
AGFileGetDBMenuName(&fileSpec, menuName);

IS YOUR GUIDE DATABASE OPEN?
As mentioned earlier in "What Systemwide Help Means," you can't assume your guide database is always open, even if the user invoked it from within your application. To cope with this fact of life, your application should call the AGIsDatabaseOpen function when it's switched from background to foreground, passing in the database's reference number, to see if its guide database is still open.

if (AGIsDatabaseOpen(myAGRefNum))
    ;   // The database with myAGRefNum is open.
else
    ;   // The database with myAGRefNum isn't open; someone else closed it.

If AGIsDatabaseOpen is true, you can also assume that Apple Guide is active. If AGIsDatabaseOpen is false and you haven't explicitly closed your database, another application or the user has closed it.

STARTING UP APPLE GUIDE
You can start up Apple Guide with either the first available guide database or one you specify. You can also control the initial view the user sees, choosing from seven different options. In this initial view you can present the user with a list of topics related to the context, or you can skip the initial view and instead take the user directly to a help topic.

DEFAULT STARTUP
The default startup, the quickest and easiest way to start up Apple Guide, opens the first available guide database. The database must be in the same folder as your application (the Finder is an exception -- its guide databases are in the Extensions folder). The mechanism is similar to what happens when the user selects an item from the Help menu.

The default startup is accomplished by calling the AGOpen function with the kAGDefault flag:

err = AGOpen(kAGDefault, 0, nil, &myAGRefNum);

A reference for the database that was opened is returned in myAGRefNum. You must use this reference when you close the database.

Apple Guide starts up with the frontmost application's guide database and the startup conditions specified in the database. If more than one Apple Guide database is available for the application, the first database of type kAGFileDBTypeHelp is used. If no database is present, the error code kAGErrDatabaseNotAvailable is returned and Apple Guide doesn't start up.

DATABASE OTHER THAN THE DEFAULT
An application can also open a specific guide database when it starts up Apple Guide, by specifying the FSSpec for the database in the AGOpen call:

err = AGOpen(&myGuideDatabaseFSSpec, 0, nil, &myAGRefNum);

See the earlier section "How Many and Which Guide Databases Are Available?" for a suggested way to get a database FSSpec.

VIEW OTHER THAN THE DEFAULT
Apple Guide offers seven startup view options. This is normally controlled by the guide database; however, these defaults can be overridden with a startup function parameter. For example:

err = AGOpenWithView(&myGuideDatabaseFSSpec, 0, nil, kAGViewIndex, 
          &myAGRefNum);

Six of the possible startup views are listed below. These views, which are access windows, are shown in Figure 3. Startup view number 7 is the topic or presentation window view, which is started with a different function call (described below in "Going Directly to a Topic").

enum
{
    kAGViewFullHowdy =      1,      // Full-window howdy
    kAGViewTopicAreas =     2,      // Full-window topic areas
    kAGViewIndex =          3,      // Full-window index terms
    kAGViewLookFor =        4,      // Full-window look-for (search)
    kAGViewSingleHowdy =    5,      // Single-list howdy
    kAGViewSingleTopics =   6       // Single-list topics
};

Since almost all guide databases contain multiple topic areas, they usually start up with the kAGViewFullHowdy view. If you specify a kAGViewSingleHowdy or kAGViewSingleTopics view for these kinds of guide databases, only the topics for the first topic area will be shown.

View 1: Full-window howdy

View 2: Full-window topic areas

View 3: Full-window index terms

View 4: Full-window look-for

View 5: Single-list howdy

View 6: Single-list topics

Figure 3. Six startup view options

PRIMING A SEARCH
An application can start up Apple Guide (or restart it if it's already running) in the look-for view with a list of context-sensitive topics that match a search string (a Str255). To initiate a context-sensitive search, use the AGOpenWithSearch function and include a look-for search string as follows:

err = AGOpenWithSearch(&myGuideDatabaseFSSpec, 0, nil,
        mySearchString, &myAGRefNum);

GOING DIRECTLY TO A TOPIC
Sometimes you may want to initiate help when the user clicks a Help button in a dialog or Option- clicks an interface object. In these cases, you have a good idea of the context and can bypass the Apple Guide access window, going directly to the presentation window with the selected help topic. Here's how:

err = AGOpenWithTopic(&myGuideDatabaseFSSpec, 0, nil, myTopicId, 
        &myAGRefNum);

The presentation window will appear with the first panel of the topic.

The Apple Guide authoring tool usually handles topics by name and quietly assigns a topic ID number when the database is compiled. However, you can override this automatic assignment by specifying your own topic ID. See the authoring tool documentation for information on how to assign your own topic ID numbers. Figure 4. Controls in a presentation window

RESPONDING TO APPLE GUIDE

The author of an Apple Guide database file can initiate a number of different kinds of events to which your application may need to respond. These include attaching Apple events to controls in help topics, drawing coach marks on dynamic interface objects, sending Apple events when certain panels appear, and using context checks to determine whether a presentation panel should be shown or skipped.

RECEIVING THE AUTHOR'S EVENTS
A help author can attach an Apple event to any control in an Apple Guide presentation window. The controls can be Macintosh buttons, checkboxes, radio buttons, or Apple Guide buttons (the last two types of controls are illustrated in Figure 4). The author's action specification for these controls will contain

• the target for the action (usually an application signature)
• the Apple event class
• the Apple event ID
• the optional key
• optional data for the optional key

The action might be directed to Apple Guide -- for instance, to start up another presentation window, to return to the access window, or to go to another panel in the same topic. The action can also be directed to your application; in that case, the target is your application signature, and the Apple event class and event ID are ones for which you've installed a handler. The content of the optional key/data field can be anything; how it's used is up to the application developer. Apple Guide extracts the optional data field, calculates its size in bytes, calls AEPutParamPtr with a descriptor type of typeChar, and sends the Apple event. To receive the action, install an Apple event handler for the class and event ID. Your handler can get the optional data parameter using your key.

There is no reply to this event. If you want to reply, see the section "Responding to Context Checks."

PROVIDING OBJECT LOCATION FOR COACH MARKS
Coach marks are circles, X's, underlines, and arrows that can be drawn on interface objects to direct the user's attention to them, as illustrated in Figure 5. Using such marks has been shown in tests to be much more effective than putting drawings of the objects into the help content (users tend to click on the drawing, not the real thing). The Apple Guide authoring tool provides a fairly complete set of instructions to mark many common interface objects, such as the following:

• menu titles and items
• windows and any coordinates relative to a window
• window elements such as close boxes, size boxes, titles, and scroll bars
• items that have a help balloon "hot rectangle"
• dialog items

Figure 5. Coach marks

These are all relatively static elements with locations that can be found by Apple Guide's marking facility. Some interface objects, on the other hand, are dynamically located at locations known only to the application. If you've identified a dynamic interface object using the Object Support Library (OSL), you can use Apple Guide's built-in OSL coach-marking facility to locate and mark the object. See the documentation for the Apple Guide authoring tool for details.

If you want to mark dynamic interface objects and you're not using the OSL, Apple Guide provides another method for you to use. In this method a handler installed by Apple Guide calls your application asking for the rectangle of a named object. To use this method, your application must install a coach handler that takes the object name and replies with the object rectangle in global coordinates. Here's an example. First, you install the coach handler:

AGCoachRefNum myAGCoachRefNum;
OSErr err = AGInstallCoachHandler(MyCoachReplyProc, myRefCon,
                &myAGCoachRefNum);

The prototype for a CoachReplyProc is as follows:

typedef pascal OSErr (*CoachReplyProcPtr) (Rect* pRect, Ptr name,
                      long refCon);

Apple Guide will invoke your CoachReplyProc with the name (a null-terminated C-string) and myRefCon from the AGInstallCoachHandler call. Set the value of pRect to the object rectangle in global coordinates. The following is an example of a CoachReplyProc. Apple Guide will draw the coach mark around, under, or through the rectangle provided in the reply.

pascal OSErr MyCoachReplyProc(Rect* pRect, Ptr name, long refCon)
{
    // Look up the name and return the rect in global coordinates.
    OSErr err = MyRectForName(pRect, name);
    return err;
}

Coach handlers persist across the opening and closing of guide databases. However, you must remove the coach handler when your application quits. Use the AGCoachRefNum that was returned to you in the AGInstallCoachHandler call.

OSErr err = AGRemoveCoachHandler(&myAGCoachRefNum);

RESPONDING TO THE USER'S HELP FOCUS
You can get Apple Guide to notify your application whenever a particular panel is being displayed (in other words, whenever it's the user's help focus) by taking advantage of Apple Guide's authorable actions. To do this, use the authoring tool to attach an Apple event of your choosing to an "On Panel Show" or "On Panel Hide" action. When the panel is shown or goes away, the Apple event is sent to your application, which can then respond appropriately. For example, it might be useful to attach an Apple event to an "On Panel Show" action for the last panel in a series of instructions, to signal that the user has reached the end. See the authoring tool documentation for information on how to attach an Apple event to a panel action.

RESPONDING TO CONTEXT CHECKS
Apple Guide can use context checks to get information about the user's environment and, based on that, to decide which panels to show in a presentation window. This enables the Apple Guide author to tailor the help to the user's current context. It gives an individualized feel to the instruction and avoids requiring the user to navigate through irrelevant information, things that users appreciate a lot. When you integrate Apple Guide, the user's context will usually be your application. The help author will want to use information from your application to determine what help the user needs. You'll need to respond to these context checks by installing an Apple event handler, processing the context check, and returning true or false.

Here's how it works: An author attaches conditions to selected panels. These conditions can be based on context checks or on user controls in other panels. While the user is reading the content of a presentation window, Apple Guide looks ahead to see which panel to show next. It evaluates the conditions, including context checks, attached to each panel. When Apple Guide evaluates a context check, it invokes the Apple event handler for the context check. The results of the evaluation based on the context check determine whether the panel should be shown or skipped.

Context checks are usually encapsulated as Apple Guide "external modules" andattached to a database. An external module is a code resource that executes inresponse to the query from Apple Guide. Creating and using external modules is outside the scope of this article, but see theTContext::ReplyToContext function in the sample code for an example of how to handle context checks from within your application.

Apple Guide handles context-check queries similarly to coach-mark queries. You install a context- check handler and Apple Guide calls it. First, the installation of the handler:

AGContextRefNum myAGContextRefNum;
OSErr err = AGInstallContextHandler(MyContextReplyProc, eventID, myRefCon, 
                &myAGContextRefNum);

The prototype for a ContextReplyProc is as follows:

typedef pascal OSErr (*ContextReplyProcPtr)(Ptr pInputData,
                      Size inputDataSize, AEEventID eventId,
                      Ptr *ppOutputData, Size *pOutputDataSize,
                      long refCon);

When Apple Guide needs to do a context check, it invokes your callback with the context-check inputData and eventId. It also passes the refCon that you provided in the AGInstallContextHandler call. The ContextReplyProc should use NewPtr to create a storage area for a short, set *ppOutputData to the value of the pointer, and set *pOutputDataSize to sizeof(short). Always return a pointer to a short. Apple Guide will dispose of the pointer.

You're probably wondering why we didn't pass a Boolean instead of *ppOutputData and *pOutputDataSize. The reason is that the context reply is a special case of a more general reply mechanism, which I'm not going to go into here. Just take my word for it -- it has to be this way.

Context handlers persist across the opening and closing of help databases. However, you must remove the context handler when your application quits. Use the AGContextRefNum that was returned to you in the AGInstallContextHandler call.

OSErr err = AGRemoveContextHandler(&myAGContextRefNum);

If you just want to field Apple events that don't require a reply, see the earlier section "Receiving the Author's Events."

MODIFYING HELP CONTENT

So far, we've talked only about main guide database files, the standalone files that support all or part of an application. You can modify the content of a main guide database by mixing in a mix-in guide database.

When a field upgrade involves new features and you don't want to release a revised guide database, you can use Apple Guide's mix-in files to add help content to the main guide database file. The mix- in files don't appear in the Help menu. When Apple Guide starts up, each mix-in file is merged with a main guide database file of the corresponding DBType. Multiple mix-in files can be mixed in.

The process is automatic, but the guide database author can control it by using Gestalt selectors. Each guide database file contains three Gestalt selectors. The selectors must evaluate to true in order for a main database to appear in the Help menu or a mix-in database to be mixed in. The Gestalt selectors in a given file are combined using Boolean OR logic. Empty Gestalt selectors are ignored. If all Gestalt selectors are empty, the file is unconditionally accepted.

There's a really cool way for the programmer to handle this. If the first Gestalt selector is the literal 'QLfy', Apple Guide will call a code resource of type 'QLfy' in the database file. If the code resource returns true, the database file will be mixed in; if it returns false, it won't be. The prototype for the code resource is as follows:

short(*QualifyFuncType)(void);

The AGFile library described earlier provides accessor functions that you can use to get the selectors and their values from any database. Only the authoring tool can change the selectors, however.

QUITTING APPLE GUIDE

When you've finished using a guide database, use the AGClose function with a pointer to the AGRefNum for the database.

err = AGClose(&myAGRefNum);

This will close the database and leave Apple Guide running in the background. When you've finished with Apple Guide, use the AGQuit function.

err = AGQuit();

This will make Apple Guide quit. If you attempt to call AGQuit without first closing the database, you'll get a kAGErrDatabaseOpen error.

If you start Apple Guide from your application, you should make it quit. Otherwise, the Apple Guide background application and help window will hang around without your application and consume system resources. This persistence is a result of the fact that Apple Guide is available systemwide. Even if the user quits Apple Guide by clicking the Cancel button or the close box, you must still balance every AGOpen function with an AGClose.

STEPS TOWARD INTEGRATION

Now you know what's involved in integrating Apple Guide into your application. If you're starting with a new product, you can build the use of Apple Guide into its design from the beginning; this can provide you with a competitive edge. If you're revising an existing product, you can add Apple Guide as a key feature. In either case, the instructional designer or technical writer should work closely with the software engineers to include an interactive task-oriented guide as an integral part of the design. Here's a suggested plan for doing that: 1. The instructional designer prepares a specification for how the application, Apple Guide, and the paper documentation will work together. The specification should include a description of the information that the guide database needs from the application and vice versa -- for example, how help is started, Apple events, context checks, and coach-mark locations. 2. The software engineers use the instructional designer's specification to add the necessary Apple Guide features to the application. 3. The instructional designer authors the database. 4. The use of the guide database is included in the application's test suite.

PUTTING IT ALL TOGETHER

It's up to you and your database author to assemble Apple Guide's features into useful and coherent help for your user. This section gives some suggestions for making Apple Guide as helpful as it can be.

MULTIPLE DATABASE FILES
You should provide different guide database files for different needs. Apple Guide database possibilities include the following:

• an Apple Guide "agent" that guides the user through a task
• a tutorial to provide basic instruction
• command reference
• application shortcuts
• databases that match the user's level of experience
• a "here's what's new in this release" database instead of a read-me file (Marketing will love it!)

HELP EVERYWHERE YOU NEED IT
Your user should have access to help under all conditions. Here are some possibilities:

• from the Help menu
• from a help button in your tool palette
• from a help button in your modeless alerts and dialogs from a help hot key, enabling the user to click an object and bring up a relevant help topic

CONTEXT SENSITIVITY
You, too, can use the buzzword "context sensitive." Use the Apple Guide features to provide "smart" help -- help that's tailored to the user's current context:

• Start up Apple Guide in the look-for view with a list of context-sensitive topics.
• Bypass the access window and go directly to the presentation window when the user initiates help from a control.
• Respond to the guide database author's context checks.
• Selectively mix in database content.

INTERACTIVITY
The built-in features of Apple Guide provide a high degree of interactivity. You can provide even more with integration:

• Identify dynamic interface objects with coach marks.
• Have Apple Guide notify you when the user is at a particular help panel (the help focus) so that your application can respond appropriately.
• Have your help database author add user controls that send Apple events to your application. Use them to allow the user to interact with you.

NEXT STOP, GOLDEN MASTER

This article has covered the basics of how your application can integrate Apple Guide. There's more in the complete API, but you have enough here to get started. With or without integration, the help system is there to serve your user. It shouldn't be compensation for bad interface design, nor should you add it just to save money on manuals or user support. Help is there to make your user moreproductive with your product, leading to a positive user experience, lots of recommendations, and sales, sales, sales.

It can be done.

WHAT SYSTEMWIDE HELP MEANS

Because it's implemented as a system extension, Apple Guide is available to all applications systemwide. It's designed to help users within and across application boundaries. Apple Guide can guide a user through multiple applications including, but not limited to, the application that invoked it.

Apple Guide's systemwide nature has ramifications for everything you do with it. While it enables delivering an unprecedented level of help to users, it also presents certain programming challenges. Consider the following characteristics of systemwide help and what they mean to you as a developer.

Help works across multiple applications. Your application's guide database can guide a user through multiple applications, not just your own. You can provide help for tasks that involve system-level operations and the use of other applications.

One ramification of this is that if the user switches from your application to another one after starting up Apple Guide and without quitting your application or Apple Guide, Apple Guide will still be present and showing your guide database. This may be desirable, depending on what help you're providing. If not, the user can quit Apple Guide from the help window. Don't force Apple Guide to quit when your application goes to the background.

Help is always available to the user. Your application can always invoke Apple Guide, even if it's in use by another application. That application's guide database will be closed and yours will be opened and shown instead.

This works the other way around as well -- if the user invokes Apple Guide from the Help menu within another application while yours is open in the background, your guide database will be closed and the other application's will be opened and shown instead. Moreover, the other application can still make Apple Guide quit even if you closed its guide database to show your own.

The bottom line for you is that you can't assume that your guide database is always open, even if the user invoked it from within your application. A call for dealing with this is described later, under "Is Your Guide Database Open?"

The user is always in control. Users can quit Apple Guide at any time, even if they've switched from the application that started it up. Once again, this means that you can't assume your guide database is always open, even if the user invoked it from within your application.

ABOUT APPLE GUIDE DATABASE FILES

Apple Guide database files provide the content of the help that your application gives users. These files can be of the following two types:

• kAGFileMain: Main or normal type of Apple Guide database file
• kAGFileMixin: Mix-in database file, which modifies a main database file with updates and additions atrun time

Files of both types have a creator of kAGCreator, which is 'reno', and are further subdivided by database type according to the type of help information they contain. The database type is stored as part of the database content and determines where the file is represented in the Help menu, as indicated in Figure 2.

Apple Guide supports multiple guide database files but only one of each type, except for kAGFileDBTypeOther. You can have multiple kAGFileDBTypeOther files; they're added at the end of the Help menu, ordered by filename.

All Apple Guide database files located in the same folder as your application will be represented in the Help menu. (Note that aliases will work as well as database files themselves, but that folders nested within your application's folder will not be searched.)

If you don't want a guide database represented in the Help menu, you should separate the guide database from the application. In this case, you must provide a mechanism in your application to start up Apple Guide with that database, since the user can't do it from the Help menu. The section "Starting Up Apple Guide" tells all about this.

Databases can also have your creator and type, allowing you to use your own document icons. Databases identified this way won't show up on the Help menu and must be opened from your application.

Figure 2. Menu items identified by database type

JOHN POWERS (AppleLink JOHNPOWERS), MWM, Apple employee, seeks intense relationship with software. Enjoys object-oriented design, craftsmanship, classical music, long walks, quiet moments, laser discs with popcorn, travel, engaging novels, and kinky polymorphism. Software must be willing to share time with extended family. Documentation a must. *

The Apple Guide Developer's Kit will soon be available from APDA (if it isn't already). It contains everything you need to author databases and integrate Apple Guide. Included in this kit is an authoring tool that compiles help content written with a standard word processor into an Apple Guide database file. The kit also contains sample help content files and documentation. *

Thanks to our technical reviewers Peter Commons, Winston Hendrickson, Josh Jacobs, Dave Lucky, Dave Lyons, and Eric Soldan.