Last Week on My Mac: Excitement and despair

For the last week new and changed features in macOS have been stampeding past in the many presentations of WWDC. Now the dust is settling again, we can pause a moment and reflect, as I hope Apple does. My overwhelming impression is that Apple needs more technical authors and fewer engineers if anyone, including its own staff, is to get the best from macOS and its sister operating systems.

It has been over a decade since Apple dropped the ball with documentation, when it stopped maintaining its many programming guides. Concurrency is a good example, where the Concurrency Programming Guide was last revised on 13 December 2012, and has since been consigned to Apple’s documentation archive. Way back in 2007, when Amit Singh wrote his monumental account of Mac OS X, he listed ten different examples of user-level threads and processes, euphemistically described as “an unusually large number of mechanisms and interfaces”.

Looking quickly through Foundation alone, there are now at least five APIs:

RunLoop
Thread
Operation and OperationQueue
BlockOperation
Process.

Then there’s separate information about what used to be branded as Grand Central Dispatch (GCD), now known simply as Dispatch.

If that isn’t incoherent enough, Swift 6 consolidates its own approach, including another half a dozen:

asynchronous function/method
asynchronous sequence
Task and Task Group
Actor
Concurrency Domain
Sendable Type

none of which refer back to anything previous, such as Dispatch.

Ask a simple question such as whether my Swift code, which currently puts Processes into OperationQueues for concurrent execution, would benefit from being rewritten to use any of the options offered in Swift 6, and there’s nowhere to find out, although I’m sure there are many others facing similar problems.

While virtualising macOS on Apple silicon is more specialist, macOS Sequoia brings radical changes that somehow escaped presentation at WWDC, leaving us trying to make sense of terse information scattered through its low-level documentation, with the aid of example code that hasn’t been updated since WWDC in 2023, so omitting all reference to this year’s changes.

There are some clues given on major new APIs, such as those for Writing Tools in Apple Intelligence, but even those are patchy and conflicting. Apple reassured us that “if you’re using any of the standard UI frameworks to render text fields, your app will automatically get the ability to use Writing Tools.” But that appears to make the assumption that the text view is already using TextKit 2, and the only documentation that I can find about that states that NSTextViews need to be opted into that with additional code. However, the class documentation for NSTextView doesn’t even mention TextKit 2, although it does now include some information about support for Writing Tools.

Turning to another part of macOS that has been undergoing constant and rapid change, almost everything in SwiftUI appears to have changed for Swift 6 and this year’s operating system upgrades. Much of this appears to be the addition of copious attributes like @MainActor @preconcurrency to protocols and much else, presumably to cope with strict concurrency checking, but there are a great many other changes that could catch you unawares.

Producing good systematic documentation isn’t just important for third-party developers, but it’s even more essential for Apple’s own engineers. Now that so many apps bundled in macOS rely on SwiftUI it makes you wonder how those maintaining them can possibly cope with this pace of change, and absence of information. How many bugs in Sequoia will be the result? Systematic documentation is also invaluable for the engineers developing code. It’s often only when you come to explain what your code does that you realise that it doesn’t actually do what you think it should.

While the new and improved features in Sequoia and its sisters fill me with excitement and hope for the future, their lack of documentation fills me with deep and growing despair.