Your application is probably so amazingly intuitive and self-explanatory that supplying Help content would be an exercise of supreme redundancy, but you gotta wire that Help menu up to something before you ship, and making it open your stupid crappy blog in a web browser is kind of a cop-out. So you decide to put together some Help content that will look nice and pretty in Apple's Help Viewer, but when you go to see what it is you need to do to make yours as fancy as theirs, you discover that most of Apple's documentation regarding Help content predates OS X and wasn't very good to begin with. This sorry state of affairs will invariably lead to several days worth of iterative development (i.e. trial-and-error) as you struggle to get your scripts and stylesheets working the way you want them to.

Help Viewer uses WebKit these days, so you can and should be previewing all of your Help content in Safari, but Safari doesn't mimic Help Viewer's indexing features, nor does it share its ability to run AppleScripts with special anchor tags or any of that malarkey. If you want to see what your content is going to look like in Help Viewer, you have to view it in Help Viewer, and if you want to test your help buttons, you need to make sure that you're pulling up the most recent version of your Help content every time you build your app. In theory, this sounds simple. XCode should see that the content has changed and copy the most recent version into your application's resource folder. In practice, nothing about XCode is simple.

The problem is that if you don't "re-index" your Help content before you build, Help Viewer's just going to pull up whatever stale version it has cached. Apple supplies an application which does this indexing for you, but it looks like it took some intern about an hour to write and is a complete pain in the ass to use. Wouldn't it make more sense if XCode would re-index all this crap for you every time you built? Of course it would, that's why it doesn't do it.

Brute Force to the Rescue

Now you could simply add a "Run Script" build phase to your project and have that run Apple's indexing application at build time, but the problem with this solution is that there's no way to make this script run before XCode does its little dependencies checks, so your Help content will frequently be one build behind. We need to get a little bit fancier if we want to keep current.

Step 1:

Add your Help content to your project if you haven't already. Make sure and create folder references and not folder groups (if your Help folder is yellow, you did it wrong). Your project should now look something like this.

Step 2:

Add a new shell script target to the project.

Step 3:

Give it a name that makes sense.

Step 4:

Find that new target in your project and open up its one and only build phase.

Step 5:

Supply a script which invokes Help Indexer.app's binary directly with the path to your Help folder as its only argument. Don't worry about the input or output files.

Step 6:

Now bring up the inspector window for your primary target and add the "Index Help" target to its list of dependencies. From now on your re-indexing script will run before XCode starts building your app, and as a result, you'll always have up-to-the-minute Help content to test. You'll know it's working when you see the indexer app bounce around your dock for a second or two after you hit the build button.

Now don't you feel superior for having done all that extraneous work the IDE should have done for you? You get bonus nerd points if you timed yourself with a binary watch your internet girlfriend bought you from thinkgeek and don't think there's anything wrong with that at all.