Motivated by a recent discussion on developing help documentation for OS X applications (a HelpBook), I decided to pull together some of my personal notes over the years and post them. Hopefully my struggles will help someone.
The HelpBook structure and .plist files
The first challenge is getting the HelpBook directory tree structure right. I usually start by grabbing an existing HelpBook of mine and changing the files under the pgs directory. I store all HTML files except the top HTML file in this directory. Of course there are a few other things to change like the icon and names in the .plist file.
The second challenge is getting all the variables in the application's .plist and the HelpBook's .plist files set and properly coordinated with each other and with the file and directory names you use (this is part of the reason I re-use the same structure over and over). Below is a diagram of my directory structure (starting at my SVN trunk) and application and HelpBook directory trees.
Adding an index to the HelpBook
The third challenge is adding the index to the HelpBook. Apple's help system will use this when the user searches for words. You get the added benefit of syntax checking your XHTML structure because one minor mistake and hiutil barfs and stops processing. Actually, by default it barfs silently, so you won't realize there is a problem. That is why you should use the "-v" option and watch the output.
I do all this from the command line. My current working directory is the HelpBook's Resources directory. Here are the commands I use:
$ hiutil -Cavf /tmp/MyHelp.helpindex English.lproj $ hiutil -Fvf /tmp/MyHelp.helpindex $ cd English.lproj $ cp /tmp/MyHelp.helpindex .
(Note: don't forget the '.' at the end of the last command)
Adding the HelpBook to the project
The fourth challenge is adding the HelpBook to the application. I keep my HelpBook files outside my application's development folder (but inside my SVN trunk). When adding the HelpBook (through Xcode's "Add Files"), I need to make sure “Create folder references for any added folders” is selected instead of “Create Groups”.
In my older notes I had this listed the other way around. But now when “Create groups” is selected, the MyHelp.help icon in the Xcode file list shows a folder. This is the clue that I chose poorly.
When “Create folders” is selected, the MyHelp.help icon appears as a little HelpBook bundle icon. This is the way it should look.
XHTML entities
The fifth challenge is dealing with XHTML idiosyncrasies. I'm old fashion and craft my HTML by hand, which leads to a lot of potential syntax errors (hence the importance of the "-v" option to the hiutil command above). One biggie is that Apple's Help is not HTML but rather XHTML. For the most part they are the same, but there are places, in particular XHMTL entities (i.e., for apostrophes and quotes), that bite me.
Help is cached
The sixth challenge is testing Help from within the application. When testing I've found one annoying problem – Apple caches the HelpBook so changes aren't reflected when I launch Help from my application on subsequent runs. I'm sure there is a graceful way to resolve this, but I just logout and log back in. This seems to flush the cache.
Final comments
Apple's online documentation for Help (at least the last time I checked) is outdated and sometime contradictory. Also, loading Help the first time is surprisingly slow, especially for my computers with spinning disks.
Personally, I'm very tempted to keep all documentation online in the future. Then when the user selects Help, I'll just open the web page in the user's web browser. This also makes it easier to update the documentation without needing to re-submit my app to the Mac App Store.