Designing Apple Help

by Kevin Knabe

from Interface Design & Document Design,
Edited by Piet Westendorp, Carel Jansen, Rob Punselie
Copyright 2000, Editions Rodopi B.V., Amsterdam - Atlanta

The online help system included with Mac OS 8.5 is the product of a decade of research and development at Apple into how users can work most effectively with online help. At first the team focused on developing a help system optimally designed for answering procedural ("How do I…?") questions. Later they would broaden the scope of the help to better support goal formation and error recovery. They would also switch from a proprietary help technology to HTML to assure wider adoption by application developers. The new approach was strongly influenced by the principles of minimalist documentation, along with an ongoing process of itterative design and usability testing. This article summarizes the design efforts and presents a general set of guidelines for help writers and designers.

The evolution of online help for the Mac OS

Early research

Online help for the Mac OS began to take shape in 1988 when Apple's Human Interface Group reviewed the available literature on help, evaluated existing help systems, and conducted videotaped observations of user behavior. In several studies, users were observed thinking aloud while doing tasks in application programs. The team found that users tended to represent problems in the form of questions, and that questions fell into five general categories:

• goal-oriented questions ("What can I do with this?")

• descriptive questions ("What is this?")

• procedural questions ("How do I do this?")

• interpretive questions ("Why did that happen?")

• navigational questions ("Where am I?")

Additionally they found that most questions were either descriptive ("What is...?") or procedural ("How do I...?).

Based on these findings, the designers proposed a system for asking and answering questions. A user would begin by choosing a question type, such as "What is…?" or "How do I…?" from the Help menu. Though this menu design was never fully implemented, two of the menu items eventually became part of the system. "What is…?" help took the form of Balloon Help, which was released with Mac OS 7.0. "How do I…?" help took the form of Apple Guide.

The design of Apple Guide

User testing of the Macintosh Electronic Reference - a HyperCard-based online reference for the Mac OS - illuminated many of the problems with traditional forms of online documentation. When users accessed help, they switched out of the context for doing a task. In order to follow the steps in the help, users had to repeatedly switch windows or else read and remember the entire sequence of steps. Users often skipped steps, performed steps incorrectly, or failed to branch appropriately on conditional instructions. [1]

Apple Guide was designed to address the problem of layer switching. When users access help in Apple Guide, they stay in the active application. Instructions are presented in small system windows that float on top of everything else on the screen so that help is never covered. The instruction panels present one step at a time, so that instructions are small and unlikely to cover the functional interface. The user pages from one step to the next. The help is able to skip steps that the user has already completed and present remediation when the user gets off track.

Another common problem with traditional online help is that users are confused by pictures of interface elements. They often click the pictures, mistaking them for functional interface elements. Rather than showing illustrations of objects on screen, Apple Guide points out the actual object by drawing a bright red circle (known as a coachmark) around the object, as in the figure below.

Figure 1: An Apple Guide panel along with a coachmark circling a button

Apple Guide had a standard set of information access features. A user could access help by choosing an item from the help menu. They could look up a specific help topic by using a table of contents, an alphabetical index, or a keyword search feature.

Usability testing and market research

Product teams conducted usability tests of help content as it was developed. Typically these tests would involve recruiting six to eight participants and having them think aloud while performing tasks with developmental software. Participants were encouraged to use the online help whenever they encountered a task that was unfamiliar.

Usability testing helped identify a variety of problems. These included problems with the grouping of tasks in the table of contents, inadequate search keywords, problems with the naming of individual tasks, use of unfamiliar vocabulary, and the use of panels that were too big. Generally instructional designers were able to address these problems in rewrites.

Market research indicated fairly low levels of usage and satisfaction. In focus groups, users complained that Apple Guide presented information too slowly and in inadequate depth. Although Apple Guide has been optimally designed to "spoon feed" the correct instructions to users, many users - particularly experienced users - didn’t want to be spoon fed. They wanted a more in-depth body of content that supported faster information access.

Design goals for online help in Mac OS 8.5

The experience of designing and testing Apple Guide helped inform the design of the next generation of help. In designing help for Mac OS 8.5, the designers sought to preserve the strengths of the existing system while addressing the known problems.

Design Goal 1
Make help discoverable.

The help menu introduced in Mac OS 7.0 appeared as a small question mark icon at the right of the menu bar. This design was chosen to assure that there would always be space available for the menu, even in applications with complex menus in space-intensive languages such as German.

Figure 2: Location of the Help menu in Mac OS 7.0

Many users apparently did not notice the question mark icon. In usability tests, participants often browsed through the menus at the left of the menu bar - File, Edit, View, Special - then stopped exploring. Some participants didn’t use the menu even after they were prompted to look for Help. Discoverability was identified as the number one usability problem with the help system, because for many users, it was the only problem they ever encountered.

In Mac OS 8.0, an obvious solution was implemented; the menu was moved to the left and labeled "Help." Placing the menu on the path of exploratory learning has led to a noticeable increase in the discoverability and usage of help.

Figure 3: Location of the Help menu in Mac OS 8.0

Design Goal 2
Make help easy to author.

Apple Guide was not widely adopted by Macintosh application developers, partly because of the difficulty in scripting Apple Guide databases in the absence of a dedicated authoring tool. Also, many developers didn’t want to develop altogether separate versions of help for the Macintosh and Windows versions of their applications.

It had become clear that HTML was the standard for authoring online information. It had become equally clear that the help for Mac OS should be HTML based. This would allow authors to use any of the available HTML authoring tools. It would also allow relatively easy porting of help content between the Mac OS and Windows.

Design Goal 3
Provide a central point of access to all available help.

In Mac OS 8.5, all help for the Mac OS - procedural and non-procedural, local and Web-based - is available through a central point of access. All of the help is accessed through an application called Help Viewer, which pulls together a variety of help technologies. The Help Viewer lets users display and browse content written in HTML, perform full-text searches of HTML content on the hard disk, launch Apple Guide sequences for step-by-step guidance through complex procedures, open a Web browser to a specific URL, or run scripts to automate tasks.

Figure 4: The table of content for Mac OS 8.5 Help, displayed in the Help Viewer

The Help Viewer can also display a page listing all available help "books." This page, known as the Help Center, is assembled dynamically based on the contents of the Help folder. (An application developer can have help appear in the Help Center by installing a folder of HTML files in the Help folder and including special meta-tags in one of the files.) The user can thus browse among all of the content in the Help folder, not just help for a single application.

Figure 5: The Help Center

The user can also search all the content in the Help folder. . For example, Figure 6 shows the results of a search for the string "folder actions." Some help content was found in Mac OS Help, and some was found in AppleScript Help. (The title of the help book is displayed next to the title of the article.) In this way, a user can search for help even if he or she doesn’t know what application or utility program is needed to perform the task

Figure 6: The results of a search

Design Goal 4
Take advantage of the Internet.

In phone surveys, a segment of users requested more comprehensive technical information. A great deal of this information had already been developed and was already available on Apple’s Web site. For instance, the Tech Info Library contained over ten thousand articles written by Apple’s Customer Support Division. It was therefore possible to vastly increase the volume of content in the help system by simply linking to existing content on the Web. (Notice in Figure 4 that one of the links is to the QuickTime Web Site.)

Design Goal 5
Define tasks broadly.

In writing Apple Guide sequences or other forms of step-by-step procedures, writers tended to approach a task as merely a series of actions, as illustrated below.

Figure 7: A linear task model

If users were robots, this approach would probably be effective. In reality, users are constantly forming goals, refining their goals, trying things out, seeing what happens, and deciding what to do next. [2]

Figure 8: A broader, more itterative task model

To fully support tasks, online help should assist users in forming goals, performing actions, and interpreting feedback. This represents a shift in instructional philosophy that places somewhat less emphasis on procedural instruction, while placing greater emphasis on presenting the rationale for doing a task and on interpreting feedback in troubleshooting scenarios.

Design Goal 6
Write minimally.

Although writers were encouraged to take broad view of tasks, they were also encouraged to write about only those aspects of the task that users were unlikely to figure out through exploratory learning. [3]

In usability testing of Apple Guide content, writers saw that some tasks could always be done without help. Figure 9 shows one such example. AppleCD Audio Player, an application for playing audio CDs on a Macintosh, includes help for playing a CD. In five rounds of testing with over forty participants, no one was unable to do this task without help. In other words, no one ever needed the instruction shown in the figure below.

Figure 9: Example of an unnecessary instruction

Figure 10 shows an example of the same task documented in the new approach. (At first glance, the minimalist approach may seem longer. Keep in mind, though, that Figure 9 shows only one of several screens that the user must page through, whereas Figure 10 shows help for the whole task.) Note that the procedural aspect of the task is handled in one sentence. Most of the help is devoted to troubleshooting.

Figure 10: Example of a minimalist approach

Design Goal 7
Automate tasks when possible.

Notice also in Figure 10 that a button is provided for automatically opening AppleCD Audio Player. These "do it for me" buttons are used throughout the help, usually to open the window or dialog box that must be used to perform a task. The use of automation is limited to tasks that are scriptable within an application, and which do not require user input.

When part of a task is automated, users tend to complete the task more quickly and with fewer errors. Although this approach goes against the conventional pedagogical wisdom, we have found that many users are willing to sacrifice learning in the interest of fast and successful task completion. We have also found that users can learn from an automated approach to a task; user test participants who rely on automation to complete a task at the beginning of a session often can complete identical or similar tasks without help at the end of the session.


The new approach led to remarkably high rates of task completion in usability studies. In one study, users completed tasks successfully in 21 of the 23 cases in which they used help (that is, after exploratory learning had failed). The core elements of the system - troubleshooting-focused writing, task automation, and the use of step-by-step guidance when appropriate - appear to support users well "when all else fails." Apple plans to do continued research into how well the new help system is accepted by developers and users in the field.


The information in this paper was gathered primarily from Apple internal technical reports. The author would like to acknowledge the people who contributed to those reports: Kate Gomoll, Tom Gomoll, Rachel Haas, Jeffrey Herman, Jeremy Hewes, Glenn Katz, Kristy Knabe, Gordon Meyer, Anne Nicol, Jim Palmer, Abigail Sellen, Mike Thompson, John Trumble, and Irene Wong.


    1. Knabe, Kevin J. "Apple Guide: A Case Study in User-Centered Design of Online Help," ACM/SIGCH Conference Companion, 1995.
    2. Norman, Donald A. The Design of Everyday Things, Doubleday, 1988.
    3. Carroll, John. The Nurnberg Funnel., MIT Press, 1990.