Apps can choose from a wide range of different methods for delivering help to the user, but Apple’s supported system is AppKit’s Help Manager, which integrates a local XHTML Help book with online updates and extensions. Although one of the least popular features in most apps, when you need it, it’s essential that it works properly. Unfortunately that hasn’t always been the case, so this article explains how it should work and where it may not.

Structure

Help Manager relies on four components:

• a Help book constructed in XHTML with CSS according to rules laid down by Apple, put into a Help bundle and placed in the app’s internal Resources folder in /Contents/Resources/. This bundle conventionally has the extension .help, and UTI type com.apple.help;
• the helpd service provided by macOS from /System/Library/PrivateFrameworks/HelpData.framework/Versions/A/Resources/helpd, to collate indexes and other information about Help books. This is run on demand, as a user process;
• the HelpViewer app, at /System/Library/CoreServices/HelpViewer.app, to render and display Help books using WebKit;
• the ~/Library/Caches/com.apple.helpd folder, containing indexes, databases and property lists maintained by helpd.

This top-level architecture has changed relatively little through versions of macOS from around 10.6, and last underwent major revision in High Sierra 10.13.4, since when it has changed little. The precise contents of the com.apple.helpd folder have changed, though, and for this article I refer to those in macOS 13.3.1.

The current structure of the com.apple.helpd folder is:

• Cache.db and its two supporting database files,
• CSHelpindexCache.plist, a keyed archive containing structured information about recognised Help books,
• fsCachedData, a folder containing many files named using UUIDs,
• Generated, a folder containing help indexes within folders such as com.apple.Dictionary.help*2.3.0, named by the Help book and app version,
• HelpCache.plist, a keyed archive containing further structured information about recognised Help books,
• HSTS.plist, a short property list giving information about the last connection with the help.apple.com server,
• four icu_rules_… files containing containing search information,
• index.spotlightV3, a folder containing Spotlight index data.

The last three items are recent changes.

Installing a Help book

The macOS Help system has traditionally relied on the user (or an installer) adding an app bundle to one of its two watched folders, /Applications and /Applications/Utilities, to trigger the process of adding any new or updated Help book to those available. The helpd service is activated by File System Events when that occurs, and responds by checking the app bundle for a Help book to register it.

There’s also a direct route, by calling NSHelpManager.registerBooks() with the bundle for helpd to examine. This is primarily intended for use by developers when an app needs to register additional Help books, perhaps for components installed elsewhere.

One important issue that was addressed in the improved Help system in High Sierra is the identification of Help books. Previously, that for the Dictionary app was known as com.apple.Dictionary.help, making it difficult to accommodate more than one version of an app and its Help book at a time. The current system incorporates a version number, such as com.apple.Dictionary.help*2.2.2.

When a new or updated Help book is installed, the Help book service helpd is supposed to recognise it, add it to the list of Help books which it maintains, and compile its data into its private databases and supporting files stored in ~/Library/Caches/com.apple.helpd. This is summarised in the diagram below.

Opening a Help book

When the user tries to open an app’s Help book, helpd accesses the data it holds for that Help book, and provides it to the HelpViewer reader app, which in turn displays the contents in a window, as shown below.

Opening a Help book and rendering it are time-consuming processes. Even on an Apple silicon Mac, HelpViewer can take two seconds or longer to finish loading its first page. helpd can take even longer, although most of its work is performed in the background and doesn’t affect the user. Typically, that could be as long as ten seconds.

Problems

Before High Sierra, Help Manager was troubled by several bugs, and had become unreliable prior to its major revision in 10.13.4. Since then further bugs have come and gone; among the more troublesome are those in Big Sur and Monterey, which can prevent a Help book from opening, or, if it does eventually open, the book displays completely blank pages.

Although those appear to have resolved in Ventura, three issues remain:

• Delays in helpd recognising new or updated Help books, causing HelpViewer to return spurious failures, claiming that no content is accessible. If the app is correctly located in one of the checked Applications folders, the only workaround is to leave that app’s Help menu alone for ten minutes and try again.
• Intel Macs, but not Apple silicon models, currently open the Help window behind that app’s main window. When the main window covers much of the display, this can lead the user to assume that opening the Help book has failed completely. It’s odd that Apple silicon Macs do what’s expected, and open the Help window in front.
• Strange behaviours with Stage Manager. Because HelpViewer is a separate app, sometimes Stage Manager considers the Help window is another window owned by the parent app, and sometimes it’s treated as belonging to a different app. These inconsistencies are gradually being ironed out as Stage Manager matures.

Alternatives

For developers, authoring and maintaining Help Manager’s Help books has never been easy. The only tool with a full GUI, Help Crafter, surely can’t be economically viable, although its developer continues to maintain it (thank you, Putercraft), and most alternatives involve hand-crafting XHTML. Despite those challenges, major developers like Serif continue to use Help books.

For brief Help pages, a scrolling styled text view is usually ample, while longer illustrated Help books are more easily created in PDF. Many developers now simply link to documentation on their website, ensuring that the information is always up to date. Help books seem such a wasted opportunity, but how many users now open the Help menu anyway?