Code by Kevin

Code by Kevin, Programming, code, business, and other pursuits

Your Host
Kevin Walzer, software developer.


Subscribe to RSS Feed
Get a syndicated feed of my weblog.



Privacy Policy

Site design: Skeleton


Mon, 09 Mar 2009

What is "Mac-native" user help?

If you are a regular user of any of my applications, and have upgraded through different versions of them, you'll notice that my system of providing user documentation has changed many times.

I used to provide an Apple Help book (which is displayed in Apple's built-in help viewer, and is searchable) and a PDF. Then I moved simply to Apple Help. Later I moved to an elaborate hand-rolled system written in Tcl/Tk for displaying HTML, which was searchable and included a browsable tree view of the help documents. Then I moved back to Apple Help, using a Tcl extension that wrapped the most common help functions.

When OS X Leopard was released, however, I found myself put off by the behavior of the native help viewer, which is a floating window that sits in front of every other application window on the screen. So I moved away from Apple Help, and tried putting my user help online at my website. That also presented difficulties, because what happened if there were some sort of network problem? The answer is obvious--no user help.

Finally, I decided to settle on a simplified version of the hand-rolled help system I used a couple of years ago. This was motivated partly by my desire to develop the help viewer as a more generalized HTML display that could be plugged into an application (see tkwebview at, and also by my desire to have integrated user help without the quirks of OS X's help system. I'm pleased with the results. If you take a look at the help displayed in Apple's system below, and compare it to the help system rendered by tkwebview, they look pretty similar.

User help in Apple's system...

...and in tkwebview.

The issue, though, isn't so much how they look as how they function. The help system in tkwebview stays out of the way unless it's needed. Then it pops up in a separate window in my application. By contrast, the Apple help system sits in front of everything, getting in the user's face. I consider this a hindrance to its usability, even though it offers search capabilities that tkwebview does not.

As with printing, I've concluded that the usability of the Tk-based system is superior that of the native help system; hence, I am using that in my applications.

[/software] permanent link