The Help system in macOS is another of those areas which has become sadly neglected. The last time it had a thorough overhaul was back in High Sierra 10.13.4, when it was taken off life support and left hospital walking unaided. With macOS 11 Big Sur and later it has relapsed, and in some cases can’t open an app’s Help book at all. I suspect that this may not be its fault, but the result of a revamp of UTIs, which are used to identify file types.

Many apps now choose to use their own Help systems; some time ago, I started to move all mine to PDF documents, which my own apps manage and display without relying on the Help system built into macOS. Traditional Help books consist of HTML files assembled into a special bundle, with the extension .help, inside the app’s Resources folder.

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 a private database and supporting files stored in ~/Library/Caches/com.apple.helpd. This is summarised in the diagram below.

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.

All this is dependent on helpd being able to identify the Help book bundle within apps, which I think relied on that bundle having the correct UTI, which identified its type. Consequently, Help book bundles were displayed in the Finder with a custom icon matching that UTI type.

This has changed in Big Sur and Monterey. If you inspect a Help book, it’s now displayed as a plain folder, implying that it’s no longer recognised as it has been in the past. Not only that, but macOS itself no longer matches the folder name extension of .help as representing a Help book bundle, but gives it a temporary UTI.

Apple has recently had problems with handling some UTIs, as that venerable system is in the process of being overhauled. As an unintended consequence, some system-defined UTIs have been removed and not replaced, causing problems elsewhere. I suspect that this may be at the root of the current problem recognising Help books correctly.

I’ve encountered this problem in apps whose Help books I haven’t accessed before. What usually happens is that the Help book opens blank and useless. The only solution that I’ve found is to:

• Open the app.
• From within the app, try to open its Help book.
• When it doesn’t open correctly, close the Help book and quit the app.
• Wait a few minutes and repeat the cycle a few times until the Help book opens correctly.

Once it has opened properly, you should have no further problems in opening that Help book again.

Back in Sierra, problems with Help books were so bad that I wrote a utility to improve them, HelpHelp. Because of subsequent internal changes, this stopped working, and I haven’t tried to maintain it since. However, I don’t think it would help these problems, particularly if they’re because of problems with UTIs. Hopefully Apple will address this issue shortly and we’ll be able to get all the help that we need.