It is naïve and unreal to claim that every app should be intuitive, and insulting to users not to provide help which is every bit as carefully-produced and thorough as the apps that we use. Yet Apple Help has been left to wither through successive upgrades to OS X / macOS, and the development of good help resources for apps is poorly documented (an irony in itself), and lacklustre.

Most remarkably, the current release of Apple’s Xcode SDK does not once mention Help in its own Help. Although it details every last tweak and setting that you need to make to an app to provide it for sale through the App Store, provides long checklists for debugging and testing, and even explains how to add an opening animation, Xcode’s Help fails to mention how you might add Help to your own app.

In preparing Consolation for its second release, I want to equip it, and its users, with documentation that doesn’t just explain the obvious, but which users will both enjoy and value. The question is, what is the best way to develop Help for your app?

Apple’s documentation was last revised four years ago, is now hopelessly out of date in many key respects, and is largely opaque. Xcode provides no tools to develop Help support for apps, apart from a utility which can index Help pages developed outside Xcode.

As far as I can see, there is only one complete and dedicated Help authoring tool, Help Crafter, and advice and instructional material on authoring Help seems hard to come by. In short, I need help on Help.

This first article looks at using Help Crafter; future articles will look at other methods, including the use of Eastgate’s superb Tinderbox.

Help Crafter, by Putercraft, is quite an expensive purchase from the App Store, at around £/$/€ 39, and doesn’t do much else (it does generate web output too), so has a limited market; it works fine in recent versions of OS X / macOS, including Sierra.

When started the first time it takes you through setting up personal details, which it uses in your help projects. You then create a new Help document, which presents a blank page.

At this stage, it is worth noting that Help Crafter has full support for multilingual help. You can choose from a vast range of different languages, so it appears an ideal platform for those who want to maintain several localised versions of their app, including its Help.

Help Crafter’s main window displays the hierarchy of help pages at the left, the editable content of the currently selected page in the centre, and the page’s metadata (abstract and keywords) at the right. This is a clean and efficient working environment for creating and assembling a Help bundle.

Start by adding a Welcome page. Select the only item at the left (the top level), and click on the + tool at the foot of that panel to create a new page. Select its title, and name it Welcome.

Move to the centre area, and enter the page’s content, explaining the functions of your app, and its key features, to introduce the user to its potential, and establish what Help is going to cover for them.

Select the top level [App] Help item at the left, and add another page, here titled Basic tasks, which will contain a list of links to pages describing how to perform basic tasks. For the moment, leave its contents blank.

Select the Basic tasks item at the left, and add another page, which will then appear nested under Basic tasks in the hierarchy of pages. Give it a suitable title, and edit its contents to detail the first basic task.

Add screenshots by dragging and dropping them from the Finder into your page. Rescale them in the conventional way, by selecting the image and dragging a corner in. You do not need to hold the Shift key to maintain their proportion.

Once you’re happy with the content of the page, add an abstract and a few appropriate keywords. To set up a link between the current page and any other, place the insertion point (cursor) where you want the link to go, and click on the Link tool at the right of the main tools. A sheet drops down to let you edit the link’s anchor text and the destination. Use this to populate the Basic tasks page, and to provide links between other pages as you wish.

From here, it is just a matter of using the app’s tools to create and lay out your content. There are no facilities to import Markdown documents, HTML, or RTF, but I copied and pasted text extensively from my existing documentation, written in Nisus Writer Pro. Help Crafter comes with only three text styles, but it is easy to add more, and encourages you to design clean and simple pages.

Exporting your Help bundle ready to build into your Xcode project is just a menu command away. You don’t have to pass that through Apple’s separate index builder; indeed, because your Help is turned into a bundle, you cannot.

The only place that tells you how to add a Help bundle to your project is Help Crafter’s Help. What I did was create a folder named Resources in the main app project folder, and moved the .help file generated by Help Crafter there, after simplifying its name to Consolation.help.

In Xcode, I then added that .help file to the project via the command in its File menu. However, that is not enough: you have to edit the app’s Info.plist to add two new items. Help Book directory name is set to the file name generated by Help Crafter, in my case Consolation.help. The other item is the Help Book identifier key, which is the bundle id which you assigned in Help Crafter, in my case co.eclecticlight.consolation2.help. A quick rebuild of the project should then bring everything together, and your Help finally helps others.

I did encounter a couple of minor glitches: when asked to save the Help bundle to a folder nested in my Home folder, Help Crafter complained that it did not have privileges to do so, so I saved it to the top level of my Home folder instead. I also managed to get the app to hang when trying to add a link to the footer, which was admittedly a wildly unorthodox thing to try.

If you want to add Help to your app, Help Crafter should be your first choice. It does its job with a single mind – it is straightforward to use, properly documented (unlike Xcode), and produces excellent Help files. I’m really glad that I bought it.