I’m not always as inquisitive or thorough, but Apple Help in macOS has fired my curiosity and determination to understand how it works.

My starting point and stimulus is the very first section of Apple’s Introduction to Apple Help Programming Guide, first written in 2003, last revised in 2013, and still apparently as current as it gets. It states that the Apple Help system includes three components: the Help Viewer app, the application programming interface (API) which is documented in the guide, and the Help Indexer utility.

You can split hairs and argue that includes allows there to be other components which are not listed. But I know that, by the release of Mac OS X 10.6 Snow Leopard in 2009, that list was misleadingly incomplete. There was, and remains, an on-demand service helpd, which is installed in OS X and macOS as a Launch Agent.

This may all seem very esoteric, but understanding how Apple Help works is key to understanding how it may not work. With documentation which provides only a small part of the jigsaw puzzle, aberrant behaviour becomes baffling.

Take, for example, a quite common problem among developers who build Help Books into their apps. When they build a new version, with an updated Help Book, they discover that the new version usually still uses the old Help Book. A similar problem can strike a user who is part of a beta-test programme and has both the current final and a beta release version of an app installed. If they go to use the Help, they may discover that both versions offer the same Help Book. The same goes for anyone who might have multiple versions of an app, or who does not install an app in their /Applications folder.

If you don’t know how Apple Help works, and the role of helpd and its cache of Help Book information, those problems make no sense. Search the discussion forums for a solution, and you’ll come across developers whose only workaround seems to be to make Zip archives of all the other versions of their app which are installed, and hope that Help will guess to use the right Help Book.

If one of your customers complains that the Help Book in the latest version of your product is out of date, you’ll be unable to explain their problem, or to suggest a solution. They probably won’t recognise that running that version from ~/Applications might cause this, and you’ll not know to ask.

The missing information, as I now understand it, starts from the problem faced by Help Viewer (now also named HelpViewer), which is a fairly stunted app in any case. Inviting it to open the Help Book inside your own app would of course be a simple problem to solve. But because HelpViewer gives access to all the other Help Books installed on your Mac, it needs a mechanism to let it open the Help bundles of those other apps.

That mechanism is an index file which lists all the Help bundles which are known to be installed on your Mac. HelpViewer looks those up using the Help Book signature, such as co.eclecticlight.consolation2.help, which is a key in that index. So for each signature, there can only be one Help bundle listed. HelpViewer is in no position to offer search hits from several Help Books associated with a single signature, which would be very confusing.

One of helpd‘s primary tasks is to maintain that help index, at ~/Library/Caches/com.apple.helpd. Although most of it consists of an inaccessible database, the file HelpCache.plist contains a list of those apps which do not have Help Books, but which may use their own system of providing help, and of those apps which do.

It is not feasible for helpd to have to continuously scan all the folders on your Mac which might contain apps with Help bundles inside them in case they need to go into that index. Instead, helpd watches /Applications and /Applications/Utilities for changes. When their contents change, helpd inspects newly-added app bundles, and extracts information about their help support for its index.

The index is not just used to identify which Help Book to open, but is essential for searching across other Help Books too. Depending on your current localisation, it records where to find the Help Index for each of those Help Books.

The basic lesson from all this is that, as far as Apple Help is concerned, you should keep only one copy of an app in your /Applications folder, and that should be the version whose Help Book you want to access when you open Help. If you have other versions on your disk, they should be kept out of /Applications, and you are unlikely to be able to open their Help Books without first moving them to your /Applications folder.

For me, the biggest remaining mystery is why Apple has never documented these matters, although the answer to that may rest in explaining why the Apple Help Reference manual has never been made available. It makes you wonder whether anyone still working for Apple is aware of the way that all this works. It’s like some long-forgotten wing in Castle Gormenghast.