Help with Apple Help

The Many Faces of Documentation

An important note: Speaking of The Many Faces of Documentation, be aware that Leopard’s help books look different; this guide and toolkit will make you Tiger-ish docs.

It’s important to keep in mind that the style used in the help for Apple’s applications is by no means free. The system basically just links together a bunch of HTML. So while many developers—myself included—have tried to reproduce Apple’s style in their own apps, just as many have created a more traditional help system with a table of contents and so on. Here are the two for comparison:

Ecto's Help: Table of Contents-based
Ecto’s Documentation: Table of Contents-based

Pixen's Help: Task-based
Pixen’s Documentation: Task-based

For the most part, documentation can be reduced into these two types. Each has its pros and cons, but I’d like to advocate the latter, task-based help. You see, the traditional, Table of Contents-based documentation’s primary purpose is to teach the user how to use the application. It’s a tutorial.

It makes sense, then, that Apple’s consumer software uses the Task-based documentation. This type is designed to answer specific questions that arise while using the app. You see, this design doesn’t try to teach the user how to use the software because that should be clear from the interface. Put simply, if a user has to learn how to use your software, then it’s not intuitive, and the UI needs to be overhauled.

Now, it’s true that some projects are complicated enough to warrant thorough education—take Final Cut Pro. But the majority of applications for Mac OS X should be able to present themselves in such a way that the documentation exists only to answer specific questions, not to tell the user what they should be asking.

So we’ll be covering Apple’s task-based documentation style in this interface. Sadly, Apple’s own help documentation is woefully out of date, so much of this is extracted through trial and error. I hope this tutorial still applies when you read it.

With all that said, let’s get on to how this thing actually works.

The System

Apple Help is basic. Really basic. In fact, before WebKit, one could only use certain tags and very little CSS. Fortunately, so long as you’re requiring Panther, you can safely use any CSS or HTML that Safari can handle. Javascript, on the other hand, is unreliable. Not that you should be using Javascript in your documentation anyway.

When you click the help menu item in an application, the Help Viewer basically just opens a WebKit view on HTML file inside your resources directory. This file, in turn, is expected to link to other pages. Along with the HTML is an index (generated by Help Indexer), which the viewer’s search function uses to respond to queries.

Enough talk. Let’s make a help book for our app, which happens to be called Bacon. If, for some reason, your app is called something else, feel free to substitute its name.

Making the Book

To start, we make a new folder called “Bacon Help” in the “English.lproj” folder of our Bacon project folder. All of the help-related files will live in here.

We've created a Bacon Help folder in English.lproj
Bacon Help is in place, and we’re good to go.

Now we’ll make our index.html, the homepage-like file that will be displayed when the help book is opened. We’ve got to stick a special tags in it to make things work; I’ll explain it in just a moment. We pop open a text editor and save this into a file called index.html in the Bacon Help folder:

<html>
    <head>
        <title>Bacon Help</title>
        <meta name="AppleTitle" content="Bacon Help" />
    </head>
    <body>
        <p>Hello, world!</p>
    </body>
</html>

That AppleTitle meta tag is an addition of Apple’s. The content value provided will be the displayed name of the Help Book.

Now that we’ve got our first page, we need to put add it to the application resources and stick some information about it into Info.plist. So open up the .xcodeproj and drag Bacon Help over to the Resources folder. Make sure to choose the radio option for “Create Folder References for any added folders” when the sheet pops up. Now you should have something like this:

We've added the Bacon Help folder to our project's resources folder.

We still need to update the bundle information to link together the application and its help book. So open up Info.plist and add these entries to the <dict>:

<key>CFBundleHelpBookFolder</key>
<string>Bacon Help</string>
<key>CFBundleHelpBookName</key>
<string>Bacon Help</string>

Make sure to set CFBundleIdentifier to something reasonable if it isn’t already.

Finally, we need to generate a help index. Yes, we don’t actually have any content yet or anything worth searching for, but Apple Help still needs an index to function. So open up Help Indexer (/Developer/Applications/Utilities/Help Indexer.app), drop in Bacon Help, and let it do its thing. Remember, every time you add or modify a page, you should generate a new index.

Okay, now everything is hooked up! Go compile and run the app, then try accessing the help book from the Help menu. You should get something like this:

Hello World but Help-ish!

Being Helpful

That’s very nice, but the whole point of this task-oriented documentation design is tagging pages so that users can quickly find the ones they need. So let’s learn how to do that by creating a topic page.

Create a pages folder inside of Bacon Help, and paste this into fry.html:

<html>
    <head>       
        <title>Frying a piece of bacon</title>
        <meta name="keywords" content="fry, oil, grease" />
    </head>
    <body>
        <p>Put some bacon in a skillet, turn on heat,
        cook for a few minutes, flip, cook some more.</p>
    </body>
</html>

The keywords meta tag provides comma-delimited tags for the Help Indexer to parse for searching. Make sure you pick good keywords here, or the user won’t be able to find what he’s looking for.

Now pop Help Indexer back up and drop the Bacon Help folder in again. That’s it! You’re done. Recompile, rerun, and open up the app’s help book (you may have to restart the Viewer). Search for grease and… voila!

Grease discovered!

Conform!

So we’ve got our help book working, and that’s great, but good Mac apps should conform in everything they do, including documentation. It’s got to be pretty. And by “pretty”, I mean “let’s take Apple’s HTML and CSS.” That’s more or less what I did for Pixen.

But it’s a pretty huge hassle going through, say, Safari’s help book and extracting the useful code, so I’ve put together a help book template pack containing templates for several kinds of pages, some css, and instructions. With this, you only have to worry about writing the documentation; I’ll worry about the conformity.

Get Andy’s Help Toolkit here.

The Page Types

There are six page templates provided in the toolkit, and as far as I can tell, these are the only (or at least main) ones Apple uses. The instructions included with the .zip contain more information about how they should be used, but I’ll go through them quickly here.

These screenshots are of Pixen’s help pages, which use the templates provided in the toolkit. The actual files in the distribution don’t have this much stuff—just placeholders—but these better show off what your help book can look like after you put content in.

The Access Page

This is the page that users see when they first open your help book. Simple starting points are presented on the right, but since Mac documentation is supposed to be answer-oriented rather than tutorial-oriented, it’s pretty barebones.

The “Discover” Page

Discover Page

The point of this template is to show off features of your app. It can be used either for a “discover” page or a “what’s new in X version” page or both. These are usually linked off of the access page, and there shouldn’t be more than a couple of them.

The Standard Help Page

Standard Page

The bread and butter! These are best when presented with screenshots.

The Task-Based Help Page

Task Page

This is the kind of template fry.html would use. Basically, these page types are to be used when a topic describes step-by-step instructions on how to do something. Break it down; make it really easy for your reader.

The Index Page

Index Page

This page should be used for an index of topics or a glossary. Pretty basic, but it’s what Apple uses.

The Generated List Page

Generated Page

This page is even more basic than the last, but it’s actually the most advanced of all: this kind of page is auto-generated. It’s meant to be used for listing topics in a given category. Now how do we use these pages, and how do we tag pages as belonging to a particular category?

Anchors and Categories

This particular aspect of Apple Help is particularly annoying because as far as I can tell, this information is not presented anywhere in the Help documentation. But basically, you can define categories through simple <a> anchor tags. In order to make a page belong to some category—say, “cooking”—stick this at the top of the body:

<a name="cooking"></a>

It seems like kind of a hack, but it works. A page can belong to as many categories as you like. Now, linking to a list of pages in a given category is a little more complicated. Here’s the <a> tag linking to a list of cooking topics:

<a href="help:topic_list=cooking
 bookID=YOURAPP Help
 template=css/genlist.html
 stylesheet=css/genlist_style.css
 Other=Cooking Topics">
    Cooking Topics
</a>

topic_list specifies the category name. Make sure to set bookID to the correct name of your help book. Other specifies a header to be displayed at the top of the generated page.

Help Buttons

Now that you’ve got a help book put together, you should link to it from your application’s interface. Here’s an example of a help button integrated into UI:

A Help Button in the Interface

They’re very simple to add. Just drag a help button from the Cocoa Controls and Indicators palette in IB. Link it up to some action method. Say, displayHelp:

- (IBAction)displayHelp:sender
{
    [[NSHelpManager sharedHelpManager] openHelpAnchor:@"SOMEANCHOR"
                                               inBook:@"YOURAPP Help"];
}

The trick there, as you can see, is that the target page must have some identifying anchor in it, as demonstrated in the previous section. These tags can be used for both category membership and individual page tagging.

Try to scatter these buttons all around your application. They add some color, so they’re visually pleasing, but they’re also somehow comforting to the user. “Don’t understand what to do? Well, there’s a button right here to explain.” It presents a very low barrier to understanding.

Conclusion

With the information presented in this article, you should be able to make a helpful, aesthetically pleasing help book. Just follow the instructions provided here and in the Help Toolkit. A general guideline is to have a page for every menu item or toolbar button, but use your judgment and don’t make them for things like Save As. If you have any custom UI, make sure you provide necessary explanations for that.

I hope this article has helped to shed some light on the subject of help books. Now you’ve got no excuse! Go give your apps documentation!

The Conversation {4 comments}

Katharine Osborne 10 September, 07 @ 8:52 pm

This is awesome - thanks for providing the best documentation on this on the web
kl 06 October, 07 @ 11:38 am

Anchors and Categories don’t work until you run Help Indexer on your help files!
(Help Indexer comes with developer utilities ofcourse).
mortgagevladim 11 October, 07 @ 3:06 pm

Hi everybody
I’ve found it site accidentally
The site has domain name
I’ve read many corresnondences
I want to open a new theme
The theme is up to date
By by,everybody
mortgage
Jonathan Mitchell 06 July, 08 @ 12:50 pm

Thanks Andy

A nice introduction to the topic.

Usefully, Xcode can be configured to run help indexer on your help file within the app bundle. Handles localisations too. See:

http://outerlevel.com/blog/2006/12/21/automatically-index-your-apple-help-book-with-xcode/