Last week, other journalists, Apple, Wall Street, even President Donald Trump were all getting het up about weak sales of new iPhones in China. It’s only a sign of Apple’s disease, and one which is readily blamed on all manner of external factors. Some commentators have complained that the new iPhones are too expensive, then contradicted themselves when they tried to explain away poor sales of the cheaper iPhone XR, which has been selling for a much more traditional price over the Christmas period.

I don’t think for a moment that Apple is – yet – at risk. It’s still enormously wealthy, with sales that any other corporation around the world can only dream of ever achieving. But all week I’ve been wrestling with another sign of Apple’s current disease: its execrable approach to documentation.

Two programming problems have dominated my time. The first I explained earlier in the week, and means that many apps can’t print, even to PDF, when running in Mojave’s Dark Mode. It’s not in itself a documentation problem, as Apple has mentioned the problem in release notes, but failed to describe how to implement a solution, and didn’t incorporate any fix into its major class library, AppKit.

In looking at that problem, I stumbled across another which affects even more apps in Mojave (and possibly earlier), regardless of the mode that they’re running in: printing from a standard text view, in an app which relies on AppKit to handle the processes involved, sets incorrect margins which crop the right end of every line.

This isn’t properly documented, only alluded to in Apple’s release notes for Mojave, as far as I can tell. This may relate to the change described as:
“For apps linked on macOS 10.14, the document of an NSScrollView can scroll under the associated horizontal and vertical NSRulerView or findBarView. This means that the NSClipView is sized and positioned under those accessories, and that will be reflected in the clip view’s contentInsets.
If you’re writing a document view class that observes the containing clip view’s size to determine its own size, take these contentInsets into account when you’re determining the document size, to avoid it being larger than the inset document area.”

In practice, it means that apps which expect AppKit to handle the flowing of text into printed versions of a text view can’t do so, and must reinvent their own solution to ensure that clipping of text doesn’t occur. As the only detailed documentation of TextKit and AppKit hasn’t been updated for several years and is now ‘archived’, Apple has once again broken its own main class library for app development.

Two disturbing demonstrations of this and related problems occur when printing the bundled Calculator’s Paper Tape, which remains fixed at the width of its unresizable window even if your printer (or PDF) is using A3 paper in landscape format, and Activity Monitor’s complete inability to print meaningful page content in Dark Mode.

No doubt Apple wants me to file each of these in its Bug Reporter. It’ll then demand I attach a full sysdiagnose for each, as if that was even a vaguely useful thing to do. Finally, each will come back marked as “duplicate” or “behaves as intended”, meaning that its engineers know exactly what’s wrong, but management has lost sight of any concept of quality assurance.

Faced with those problems, I turned to another app which I’ve been developing, based on Signet, my new bundle signature checker. Its next big step is going to be a tool to monitor bundle signatures for changes, something which many users and system administrators want, and which macOS could easily be doing itself.

SignetRing is going to scan your Mac’s folders looking at each executable bundle and checking its signature. It will then save those signature details, and later repeat the scan to see which have changed, when and how. To do this, I need to save signature details in a database, an excellent case for using Apple’s Core Data. Well it would be if only I could discover how to use this major feature built into both macOS and iOS.

The Core Data Programming Guide was one of the few major software development guides which Apple maintained until recently. It was last revised nearly two years ago, but now bears the hallmark of the new non-documentation policy:
“IMPORTANT
This document is no longer being updated. For the latest information about Apple SDKs, visit the documentation website.”

So I went to that link, and finally discovered that its replacements are a couple of terse articles, such as Making Core Data Your Model Layer, which lack almost all the properties of technical documentation, not even bearing information about their revision date or relevance to different operating systems.

Third-party books inevitably lag the current state of Core Data, but stress that, provided you create a new project in Xcode with the right option selected, Xcode automatically generates all the required boilerplate code which makes basic implementation straightforward if not downright simple.

That may have been true in the past, but when I created my new project for SignetRing in the current version of Xcode, no such code was created, and all attempts to follow the tutorials failed miserably. Each of Apple’s attempts to suggest what my code should be doing differs from the rest, so unless you chance on the very latest information – and I’m far from certain that I have succeeded in that – you’re likely to end up with an app which doesn’t work in spite of apparently following the instructions.

The Apple File System Reference manual looked impressive at first sight back in September last year: over 140 pages of PDF (yes, PDF), and a revision history. But when you look deeper into it, so much is unwritten in entries like:
“cpx_t
No overerview available.
typedef struct cpx* cpx_t;”
from the section on encryption, for which no overview is available either. It’s no wonder that third-party repair utilities are still struggling to support APFS.

When you don’t document your own operating system and its class libraries, it’s your own software engineers who suffer the most. When a new project comes along, like the App Store app for Mojave, its team is struggling to know how to do fairly basic tasks like date arithmetic. I know that I should file a bug report, send the mandatory sysdiagnose, and then wait to be told “behaves as intended”.

The result is an app which can’t tell today from yesterday, and has all sorts of un-Maclike behaviours. Users get fed up with what are seen as tatty products running on their $5,000 Macs and $1,000 iPhones. They may not have paid up front for macOS and iOS, but why should they pay Apple such hefty sums for only partly functional products?

When Apple’s unboxing experience is the best part of spending all this money, and from then on it’s downhill as they struggle first to migrate from their older Mac/iPhone/iPad, then discover all the quirks and failings of the software on their new device, Apple isn’t as endearing to users as its once was.

The picture these problems paint of Apple is of a company which is so obsessed with change that it hasn’t the time or resources to document anything, nor to fix bugs any more. Fixing bugs is another essential activity which is heavily dependent on good and thorough documentation.

The effects of these failures are insidious. Apple’s engineering isn’t in danger of imminent collapse, although I’m often amazed that its engineers aren’t. But unless it recognises and addresses these problems, every year in the future it will grow more inefficient, and more error-prone. Delivering software commensurate with the premium hardware products which it needs to sell will become increasingly difficult, and rare. And that will hit Apple hard.

I for one don’t want to see that happen.