by Sven Ryen

There's a known fact in application development: "Developers are not users." Making an application that meets the goals and expectations of its users is a pretty hard task — you really need to know a lot about the potential users. On top of that, novice users will expect to be helped by the documentation, should they ever run into obstacles while using your software.

Documentation can come in many formats: printed manuals, PDF/standalone documents, and online help systems. In this article, I'll cover the online help systems provided by Apple and discuss how to develop online help for your applications.

The available Help systems

There are currently three online help systems provided by Apple: Apple Help, Balloon Help and Help Tags. Let's have a brief look at how online help on the Mac has evolved.

With System 7, balloon help was introduced. Some years later, System 7.5 introduced the Apple Guide, with its extensive walk-throughs that led users through any task by using integrated on-screen animation. It was, by no doubt, a great utility. Sadly, it was also a highly complex and proprietary tool; you had to read a 500 pages book and learn a scripting language to put the guides together. It was not the ideal tool from the developer's point of view.

With MacOS 8, Apple moved some of their help content to a MacOS Help Center that was accessible through any web browser. Further following the HTML trend, a Help Viewer was included with MacOS 8.5. With Mac OS 9.2, Apple Guide is no longer supported. Mac OS X also dropped support for balloon help in favor of a new system know as Help Tags.

Apple Help

Accessed through the Help Viewer and written purely in HTML, this help system allows for quick development and offers search capabilities for the end user. In addition to cross-referenced text, you may

• Include QuickTime movies
• Use AppleScripts to automate common tasks
• Provide links to open applications for the user
• Link to online content on the Internet

All this is accomplished by using specific tags in the HTML documents. The tags are all documented in Providing User Assistance With Apple Help, a 42-page document from Apple. A development toolkit includes documentation on Apple Help, a tutorial and several Help Book examples. You really should download this toolkit, even if you feel capable of producing help pages without the need of a tutorial, as it includes an essential part: The Apple Help style guide.

Before you start authoring help for your application, you should study the style guide, as it will help you grasp the thoughts this help system is based on. The style guide is not verbose, provides short texts grouped under compelling topics. It's in fact constructed as a Help Book, so while you read it, you'll also gain experience in how the pages in a Help Book are linked together.

To get a quick introduction in developing Help Books, I would suggest reading An Introduction to Apple's HTML-based Online Help System, a MacTech article.

Balloon Help

Balloon help was introduced to answer questions like "What does that little gizmo in my window do, and why is it disabled?" It's also a neat place for developers to put Easter eggs (figure 1). The language and use of words in help balloons is thoroughly covered in chapter 11 of the Macintosh Human Interface Guidelines. If you want a more technical and detailed coverage on the use of Help Ballons, Chapter 3 of "Help Manager (More Macintosh Toolbox)" is explains everything about these balloons.

If you are creating Carbon applications, Balloon Help is no longer available, as it is not supported in Mac OS X. You should consider using Help Tags instead.

Help Tags

Although I haven't found any reports discussing why the concept of Balloon Help was abandoned, Apple has done away with them and are now offering Help Tags instead.

The text in Help Tags is, in general, shorter than what was offered trough balloon help. Whereas help balloons could include styled multi-line text and even images, Help Tags consists of one line of text. On the plus side, Help Tags are always available. You don't need to use a menu command to show or hide them. On the down side, Help Tags take a while to appear; there's no way to invoke them instantly, as you may with Balloon Help.

The concepts of Help Tags are explained in chapter 12 of the Aqua Human Interface Guidelines) (pp. 202—204). A separate PDF document offers guidelines for Writing Help Tags.

Why Should I Include Online Help?

You probably know the scenario — the application is ready to ship, you've taken every precaution to make sure the interface meets the Guidelines from Apple (You haven't? Well, make sure you do, and then return when you're done!) — there's just one tiny piece missing: The help system.

You're probably in a hurry to get the application out the door and in the hands of your users, so you toss together a rough description of the services your application delivers, and list every single feature and command found in the application.

Will such documentation help the user when he meets a problem? No. Will the user ever bother to read through the umpteen pages listing menu commands and preferences settings? No. So what use is there in providing an inadequate help system? None! In fact, you may even risk losing potential users just because they couldn't figure out how to use your application.

Let's look at how documentation is treated by the average user. Hardly anybody opens it until they encounter a problem without an immediate or obvious solution. When such a situation occurs, they'll first try to figure out what to do by exploring the interface. If they're still stumped, they may turn to other users (co-workers, friends, etc) for help. If the solution is still unsolved after asking for help, they will head for your online help system, and that system would better provide an answer to their problem.

What should the Help system include

It should include answers to any question users of your application may have. You may also want to account for both novice and experienced users, if your application provides really advanced features. Troubleshooting is an essential topic that should not be neglected.

You should always include a Getting started section that briefly covers how to use your application, and a quick outline of the most basic features it provides. If the application has recently been revamped to include new features, you may also provide a What's New section for those already familiar with the application.

When you are about to construct the outline for your help system, take a minute to think about what services your application provides. Think in general terms — do not simply list all features as they appear in the menus. What tasks will the user be accomplishing with your application? Thinking this way may help you organize the help system in a way that suits your users.

For instance, if you are creating a word processor, some of your main topics may be:

• Getting started
• What's New
• Working with documents
• Formatting text
• Printing documents
• Searching and replacing text
• Inserting graphics
• […]
• Troubleshooting
• Support information

When you assign pages to these categories, be task oriented. Under formatting text, you may (among other topics) expect to find a page named Applying styles to text, which explains how to use the style system your application provides.

As said earlier, the key to success is reading and understanding the Apple Help style guide.

What NOT to Include

You obviously should not include all information about the application in the online help system. Here is a quick list of topics that should be left out:

• Installation guidelines. A help system is not usually available until after the application has been installed.
• A comprehensive listing of all menu commands. Clearly, users know what the commands Quit, Copy, Paste, Undo, etc do. There's no need to waste the time of your users by explaining features that are well known.
• Version History. This belongs in a separate document.
• "About the author". Could you ever possible imagine a user entering online help looking for information about the author of the application?
• Legal stuff (license agreements, etc). Again, separate documents.
• Thanks/acknowledgements. Such information belongs in the "About this application" dialog that's accessed from the Apple menu.
• Registering. A far better approach is to use a menu item (or button in the splash screen) for accessing registration information. Users do not generally expect to find such information in the help system.

It's important to remember that the help system is there for the user. Users turn to Apple Help when they are experiencing problems or have questions about a feature. The Apple Help system is not a place to store all documentation for your application.

Providing help from your application

If you've used the control panels in recent versions of the Mac OS, you may have noticed tiny buttons displaying a question mark. These buttons offer direct links to appropriate pages in the Help Center. If you want to make the help system more apparent to your users, you may consider including such buttons wherever appropriate.

When and where to use the help button

"The Help button is a 21-pixel-high, 20-pixel-wide bevel button with the standard help icon. The preferred location is the lower left corner of the dialog box, aligned with the bottom of the push buttons.... If there are no push buttons or there isn't enough room in the lower left corner, the alternative location is the upper right corner." (Mac OS 8 Human Interface Guidelines, pp 86—87).

"When necessary, you can use Help buttons...to provide easy access to specific sections of your help. When a user clicks a Help button, send either a search term or an anchor lookup (which leads to a specific page or pages) to Help Viewer.

It’s not necessary for every dialog and window in your application to have a Help button. If there is no contextually relevant information in the help, don’t display a Help button." (Aqua Human Interface Guidelines, p 202, Providing Access to Help)

There you go: use the help buttons whenever necessary or appropriate. You should also be aware of how the help button is perceived when used in a window that utilizes tabs. If the help button applies to all the tabs in the window, it should be placed outside the tab panes. If it provides help in context to the active tab pane, place it within the tab pane.

Resources

Introductory Information on Apple Help

Designing Apple Help
http://www.knabedesign.com/articles/applehelp/applehelp.html
Discusses how the help systems from Apple have evolved, and the reasons for developing the current Apple Help system, by Kevin Knabe

Writing and developing Apple Help content

Apple Help 1.2 SDK 1.0
ftp://ftp.apple.com/developer/Development_Kits/Apple_Help_1.2_SDK_1.0.sit.hqx
Contains the Apple Help documentation, the Apple Help Style Guide, a tutorial, examples of Help Books and some tools to help you create and index your Apple Help content.

Writing Balloon Help or Help Tags

Guidelines for Writing Help Tags [PDF]
http://developer.apple.com/techpubs/macosx/Carbon/pdf/UsingHelpTags.pdf
Provides instructional guidelines and examples for writing Help Tags.

Technical references

Chapter 3 — Help Manager (More Macintosh Toolbox)
http://developer.apple.com/techpubs/mac/MoreToolbox/MoreToolbox-138.html
Detailed description of how to use the Help Manager, including an overview, a tutorial, and a complete API reference. This book is rather technical, but you may find useful information about Help Balloons on the following pages:

• pp 3-13, from "Default Help Ballooons […]" — 3-23, down to "Specifying the Format […]"
• pp 3-27, from "Providing Help Balloons for Menus" — 3-72, down to "Listing 3-10".
• If you are a very technical person, you may consider reading the entire chapter.

[an error occurred while processing this directive]

The Interface Mafia - www.interfacemafia.org
News - About Us - Articles - Reviews - Submit Software - Links - The Mafiosi

this page last updated on Tuesday, October 9, 2001
site design by tobyrush.com - web space by westhost.com
follow this link for copyright information