For the last few days, much of the UK has been battered by a succession of winter storms. While down in the Balmy South we don’t usually have to contend with blizzards, the English Channel coast offers remorseless rain or gales that come at you like an express train, and when we’re really lucky, both at once.

As we’re just about to enter our fourth storm since the middle of last week, I’ve once again been searching for missing documentation, which is as frustratingly tedious as the buffeting wind. This week the gaps have included Time Machine, snapshots, ACLs and WindowServer, and hot on their heels in the coming days will be iCloud.

Time Machine is a good example of what we’re struggling with so often. Over the last few years, it has undergone major change, to support backing up from APFS volumes to APFS storage. Its original design principle, using directory hard links to create the illusion of each backup being a complete copy of the original, has been abandoned and replaced with synthetic snapshots containing changed data. What had been one of its less-loved features, Mobile Time Machine, has been transformed with local snapshots, which both serve Time Machine’s backup mechanism and provide users with a valuable alternative to formal backups.

But, as I’ve pointed out, Time Machine falls between two stools: few developers go anywhere near it, and as far as Apple is concerned, it just works for users. Features like snapshots are guarded by the same cloak of secrecy that surrounds the whole of APFS, whose woefully incomplete reference manual hasn’t been extended or updated since 22 June 2020, and must now be presumed to have been abandoned.

Almost the sole exceptions to this horde of missing documentation are two excellent guides which Apple maintains primarily for system administrators and others among its enterprise users: the Apple Platform Deployment guide, last revised in December, and most of all the Apple Platform Security guide, last revised in May and being rewritten now to incorporate the changes brought in Monterey and iOS/iPadOS 15.

Exemplary though those are, they demonstrate a fundamental problem with Apple’s approach to documentation: it’s invariably an afterthought. Good engineering and technical documentation is an integral part of design and development, not something which lags release by more than six months. Apple started introducing Monterey’s first external documentation at WWDC in June last year, and for many new and changed features those presentations will form the sole account published by Apple. And it takes a further ten months before they might be incorporated into the Platform Security guide.

Users find themselves in the bizarre position that Apple introduced ACLs in 2005, documented them for developers in the File System Programming Guide (now archived), applied them to standard folders, including the user’s Home folder and its contents, at some time thereafter, but completely omitted to inform users, and deliberately withholds access to them from the GUI.

The only clue given to the user as to the presence of an ACL is the cryptic message in Finder’s Get Info dialog that an item has “custom access”. Eight years ago, there was an Apple support article which apparently explained:
“Custom: If the permissions for an item is set to Custom, the permissions have been configured in a way that is more complex than is provided in the basic user settings.”
Considering that too helpful for users, the current account of permissions in the macOS User Guide for Monterey says diddly squat about “custom access”.

Just what does Apple expect the user to think when they’re informed by the Finder that they have “custom access” to part of their own Home folder? If they’re experiencing problems with access and permissions, just what does Apple advise its users to do?

There was a day when Apple prided itself in its superb Inside Macintosh series, which was published in conjunction with Addison-Wesley and widely used by developers, system administrators, users, and even hacks like myself who were writing about Macs. There was a time when Apple saw its operating systems as empowering users, by providing them “the power to be your best”. That seems far too many storms ago, and as a result many of us are feeling long past our best.