A brief history of help

It might seem strange today, but for much of the early history of the Mac we used printed manuals and books. For developers the reference was Apple’s Inside Macintosh series, lovingly crafted by its technical authors using Microsoft Word and published by Addison-Wesley. Even Aperture (2005) and Apple’s Pro apps like DVD Studio Pro 3 (2004) came with beautifully prepared and printed manuals.

It was the introduction of Apple’s first CD-ROM drive in 1988 and its subsequent release of the first developer CD, Phil and Dave’s Excellent CD the following year that started change. At first there was a battle between nascent common document formats, including Adobe’s Acrobat, Farallon Replica, DjVu and others. In the early 1990s this led to HTML-based help books, and printed manuals became gradually replaced by electronic documentation.

Unix had a longer evolution, with the first of many man pages written for formatting using nroff in 1971. Although printed references were published later, deep piles of fanfold printout remained popular long after the rest of computing had discovered the value of desktop publishing. While much reference material was still confined to source code files, brief glimpses into how to use commands are still revealed in lightly formatted text man pages.

The release of Mac OS X 10.0 brought with it a primary help system, Apple Help, as part of Cocoa. Those creating help books wrote them in HTML saved in a folder structure like a local website, and a cut-down browser Help Viewer displayed them for the user. The only detailed account of this, the Apple Help Programming Guide, was first published in 2003, and last revised a decade later, 12 years ago.

Help Viewer started with a spartan interface, here in 2004, and relied primarily on pages stored in local help books.

Help books can contain localised versions to support their use worldwide.

Although seldom used, you could build your own custom help book, as shown in this demonstration I created for the UK magazine MacUser in 2006.

Apple reserved /Library/Documentation/Help and its sibling in the user’s Home library for its own use, and from OS X 10.6 third-party help books were expected to be stored as a .help bundle in the Resources folder in an app’s bundle. HelpViewer.app was hidden away in /System/Library/CoreServices, and helpd was an on-demand service to watch Applications and Utilities folders for newly-added apps containing help bundles, and register them with macOS.

By 2017, HelpViewer’s toolbar offered Back and Forward buttons, a button to hide or show the sidebar, and one to share the current page.

Searching help was aided by an index built by Help Indexer during authoring (below, from 2006), and used Spotlight’s local search powers.

Unfortunately, help became neglected and started to deteriorate. During macOS High Sierra 10.13 to 10.13.4, it was revised internally, and the way that helpd worked was improved.

The macOS help system had previously 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 was activated by File System Events when such an event occurred, and responded by checking the app bundle for a help book to register it. If an app was installed in another folder, even ~/Applications, then its help book might not get registered properly.

Identification of help books also changed. 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 new system incorporated a version number, such as com.apple.Dictionary.help*2.2.2.

When originally developed, the great majority of help books relied on static content built into them. All that had to happen for most was the launch of HelpViewer, and for it to open the supplied Help book.

Since then, help books had increasingly relied on online content, which needed to be refreshed before each access. Thus HelpViewer and helpd had to work together to deliver the latest content, with helpd doing the refreshing and updating to the databases in ~/Library/Caches/com.apple.helpd, which HelpViewer used with the WebCore rendering engine to display pages and interact with the user.

Since then further bugs have come and gone; among the more troublesome were those in Big Sur and Monterey, that could prevent a Help book from opening, or, if it did eventually open, the book displayed completely blank pages.

It also had some more amusing moments, including a phase in which the help system decided that I wanted to read Apple Configurator’s help book in French.

For Ventura, Apple revised the help system further, and renamed HelpViewer to Tips while keeping its formal identifier as com.apple.helpviewer, and it remained hidden away in CoreServices. In Sequoia, it leapt from version 10 to 15 and joined Apple’s first league apps between Time Machine and TV in the main Applications folder. But if you want to read the documentation for any command tool, you still have to refer to its man page.