There are times when we all need help with our Macs. Even back in those halcyon days, perhaps with System 7 or Snow Leopard, when our memories insist that everything was so much easier and amost instinctive, we had questions which were tricky to answer. Of course in those days, Apple provided copious documentation for users and developers. Its printed Inside Macintosh series was wonderfully written, beautifully designed, and almost comprehensive.

It’s just as well, because in the heyday of System 7, in the early 1990s, alternative resources were limited, and hardly anyone had access to the emerging web. Even when Snow Leopard was current, in 2009, we were more reliant on printed sources such as the major Mac magazines like the UK’s MacUser, than on what we could obtain from the web.

What has largely replaced printed books and magazines is at best a mixed bag, and often worse than useless. Apple now produces few coherent or systematic accounts of anything about macOS. What it does publish online are generally short notes addressing specific issues. Compare these articles with the volumes of Inside Macintosh, for example, or a feature in a printed Mac magazine, and the contrast is stark. If your attention span is measured in a few minutes at most, you might find Apple’s notes suitably brief, but for most of us they bring little understanding and are barely adequate.

Beyond those notes, we rely on search engines which have no interest in, nor metric for, quality of information. You’re more likely to discover commercial or sponsored sites trying to get you to buy a Mac housekeeping app, with incorrect or out of date recommendations, than anything accurate or current.

The Mac is now in the midst of a documentation crisis. Apple’s headlong rush to change so much in macOS (and its other operating systems) every year is supported by a huge number of engineers, but its output of documentation has steadily fallen.

Its new file system, APFS, which was released more than two years ago, is addressed by just a handful of articles spread across Disk Utility’s Help and a few support notes. Its reference documentation is woefully incomplete and hasn’t been updated for nine months. Information for users about Catalina’s new boot volume layout is similarly almost absent, and there’s no official roadmap showing the new directory hierarchy at all.

Commentators continue to criticise Apple for the many bugs which remain unfixed in existing parts of macOS, and their augmentation by new bugs introduced in recent changes, which they argue is increasing Apple’s ‘technical debt‘. What few consider is the growing documentation debt which Apple has created and is accelerating with every new release of macOS.

A serious example of this are the changes which have been made to Safe mode in Catalina. According to Apple’s sole support note, last revised over two years ago, about this major diagnostic and troubleshooting tool in macOS, starting up in Safe mode “verifies your startup disk and attempts to repair directory issues, if needed”.

In Mojave, this appears to be the case. Anyone making Time Machine backups, or using another scheme which creates APFS snapshots, will have to wait maybe over half an hour for fsck_apfs to work steadily through verifying every snapshot, just as happens when you use Disk Utility’s First Aid to check an APFS volume when running in normal user mode.

Try booting in Safe mode in Catalina, and your Mac starts up almost as quickly as in normal mode, as that doesn’t happen any more. As I have concluded here, Catalina changes the way that Safe mode works, but Apple hasn’t reflected that in its documentation. Neither has Apple noted the protracted boot phase required to check existing snapshots in Mojave.

Since I started this blog almost five years ago, I have tried to include an eclectic range of articles covering macOS and Macs more generally. These cover a broad range of topics for as wide an audience as I can manage. Among them are many tackling basic concepts and problems, and you may have noticed that I have recently been publishing quite a few of these, for instance explaining how apps work and run, another of Apple’s blind spots.

In some cases, I’m updating old articles, which I first wrote in the period 2015-2017. Reading back through those, it’s amazing how much has changed since then in most of macOS, and Macs themselves. No models had T2 chips, whereas today the only new Macs you can buy which don’t are iMacs. The only file system was the venerable HFS+, and Time Machine had changed little for some years. There was essentially nothing by way of privacy protection, and many apps were still completely unsigned.

If you find these updated articles of little interest, I apologise: I am still researching, writing and publishing here articles covering new and more technical issues in depth, such as my current series looking inside Catalina’s new RunningBoard subsystem and Catalyst apps. But the documentation crisis has now reached the stage where even basic user procedures are detailed incorrectly. No wonder so many Mac users seem to be floundering around in the dark.