So as I was preparing to release my first Cocoa application (Deductions), it was necessary to write a help book. I am not a technical writer, but since I am on a budget, I could not outsource this task. I began by looking at help books of applications I liked, and it became clear that many help books were written as an afterthought, and were shockingly poor.
The Good Books
I took the help books of two applications as models for my own help book. First, Affrus from Late Night Software. Affrus came to my attention after John Gruber specifically discussed the virtues of its help system on Daring Fireball. The outstanding help book included with Affrus has chapters so that it can be read like a book, it is extremely thorough, and it is wiki-like in its cross-references. As if this weren’t enough, Affrus also comes with “Getting Started with Affrus,” a professionally written PDF file to get new users started.
Second, Pixelmator from the Pixelmator Team. This application sports the most visually engaging help book I have ever used. It is slick, organised by topic, and makes liberal use of images for illustrative purposes. It is also only one part of the Pixelmator help system: the help book links to a series of task-oriented online tutorials.
Ideally, my goal was to combine the best parts of the help books of Affrus and Pixelmator. I knew I could not match the professional style of Affrus or the beautiful layout of Pixelmator, but it seemed good to aim high. I wanted a help book with the following features: (i) be as comprehensive and clearly written as possible; (ii) may be read as if it were a book but also easily searched; (iii) have cross-references wherever it made sense; (iv) make use of images and multimedia.
Help Books
A help book, it turns out, is straight HTML with a few specialised additions. First, you need to add the Apple meta tags to your index page:
<meta name="AppleIcon" content="myapphelp/images/AppIcon16.png">
<meta name="AppleTitle" content="MyApp Help">
Without these tags, help simply will not work (and note that these tags are case-sensitive). Second, you need to add the following items to your application’s Info.plist file:
<key>CFBundleHelpBookFolder</key>
<string>myapphelp</string>
<key>CFBundleHelpBookName</key>
<string>MyApp Help</string>
Third, you need to add a title to each help page, in order for your help book to be searchable through the “Ask a question” field in the help app:
<title>Title Here</title>
And that’s all there is to it. You can, of course, build more functionality into your help book by means of other tags (you can read up on all the gritty details in Apple’s guide), but this is the minimum you need to get everything working. Run Help Indexer on your book, and you’re good to go.
Design
When writing my help book, I settled on using VoodooPad for several reasons. First, I had it handy, since I use it for keeping notes. Second, I didn’t want to write the HTML by hand, and it exports to HTML with ease. Third, it does all sorts of crazy cross-linking, of the sort you find in Affrus help; but I didn’t want to have to hand code that either. Fourth, you can add pictures and screenshots simply by pasting them in.
The thing is, once you export from VoodooPad, you still have to add some tags. I’m no expert in Ruby, but I was able to whip up a hand little script that would allow me to do this:
!/usr/bin/ruby
# Change method
def Change(file, regex_to_find, text_to_put_in_place)
text= File.read file
File.open(file, 'w+'){|f| f << text.gsub(regex_to_find,
text_to_put_in_place)}
end
# Add the apple-specific meta tags to index.html
Change('index.html',
/6\">
<style type="text\/css">/,
"6\">
<meta name=\"AppleTitle\" content=\"My Help\">
<meta name=\"AppleIcon\" content=\"AppName%20Help/images/icon-name.png
\">
<style type=\"text/css\">")
# index.html: Add title - have one of these for each .html file
Change('index.html',
/<title></,
"<title>Index of topics<")
There is doubtless a way to automate the process further, but this does the job for me.
Tips
In my experience, registering help in your application can be a little temperamental. You must run your help through Help Indexer.app to get it to work with your application. Help Indexer may be found in /Developer/Applications/Utilities/. It is a bare-bones program, but it gets the job done. Just make sure you go into preferences and select “Generate summary text if not specified” and set the correct language for the stopwords. If all goes well, and you followed Apple’s guide for setting up help in your application, your help book will now appear when the user asks for help.
Second, you may run into a problem when you update or replace a current help book. I have found that, on occasion, the old help book will be displayed instead of the new one. The way out of this is to delete ~/Library/Caches/com.apple.helpui. Why this is required is somewhat of a mystery to me, but you can solve all sorts of help-related problems deleting this cache file.
Third, if you want to embed videos in your help book, you can do this in the same way as you would a web page. I think videos are a great idea, especially for “getting started” pages. It lowers the bar for entry, especially for users who learn visually. I wouldn’t be surprised to see this appear more often in help now that Quicktime X for Snow Leopard has build-in screen recording. But if you need something a little fancier, or do not have Snow Leopard, I recommend ScreenFlow. It’s elegant and easy to use, and it even works well on my venerable PowerBook G4.
Resources
All ready to write your first help book, or make the help book you have better? You could do worse than start with Matt Neuburg’s screencast on writing help books. Matt is one of the best technical writers on the platform, wrote Affrus help, and actually makes his living, in part, by writing help books. He also has some comments about writing help books. Also, you might be interested in this discussion of common pitfalls. Good luck, and may we all get better help!
