This week I’ve had enormous fun, and untold frustration, going back to being a developer, at what feels like the sharp end of Apple’s products. Not that it should have felt that way: what I have been trying to do should be well-documented, and well-trodden territory. Like so many things now, the pace of change is so great that the mundane is avant garde.

If you think that macOS is poorly documented, try some of the basic scripting tasks that I have described here during this past week. Don’t leave it too long, though, because even the language, Swift 3, will next year become Swift 4, bringing further change. Just as Apple’s own documentation is starting to catch up, and some books and blog articles come back into sync, they’ll be rendered out of date.

In a very respected iBook on Cocoa programming in Swift, published electronically in April 2015, the following code example was given to show how to run a command in the shell:
let task = NSTask()
task.launchPath = path
task.arguments = arguments
task.launch()
task.waitUntilExit()

Just a year later, in an excellent blog article published on 12 May 2016, this had changed to:
let task = NSTask.launchedTaskWithLaunchPath(path, arguments: arguments)
task.waitUntilExit()

Less than six months later, with the release of Swift 3, this changed again to:
let task = Process.launchedProcess(launchPath: path, arguments: arguments)
task.waitUntilExit()

That is a fearsome pace of change, a bit like renaming several panes in System Preferences every six months. That is compounded by the fact that Apple’s own docs have still not caught up with it, as I illustrated here.

There’s some deep irony here too. Swift has the added attraction of being one of the few programming languages which supports sophisticated structured documentation by marking up embedded comments. It goes without saying that the only thorough documentation of this feature is in a third-party book, by Erica Sadun.

Well-resourced third party developers must have to devote a lot of time and effort to tracking these changes, and updating their source code to keep pace. As with most problems in life, it also has unintended consequences: one of the key issues raised by the XcodeGhost malware, which came close to shutting much of Apple’s iTunes app store just over a year ago, was the reluctance of many developers to keep up to date with the latest version of Apple’s Xcode SDK, and the difficulties they faced in trying to do so.

When any product, particularly your platform’s major development environment, is changing so fast that your own documentation teams cannot keep up with that pace of change, it is surely time to step back and look critically at how users are coping, and whether you shouldn’t be devoting more resources to both improve and deepen the documentation and supporting materials. These might appear to be mere details, but they are vital to users.

What I see at present in Apple is an imbalance between engineering (development) resources and those devoted to documentation and other support materials, and between implementation of major changes to generate new versions, and fixing non-critical bugs and poor features. Although I am delighted that Sierra has successfully addressed several major problems with El Capitan, a lot of long-standing more minor issues, such as bugs in the Finder, have just been ignored.

In the relatively few months before Apple is likely to announce the next major version of macOS at WWDC 2017, and the first appearance of Swift 4, let’s hope that Apple can divert its resources to document, support, and clear some more of the long list of outstanding bugs and problems in its developer tools and macOS itself. Innovation should never be incessant; we also need phases of consolidation.