June 94 - Giving Users Help with Apple Guide
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 thepresentation 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.