Apple, and Tim Cook in particular, has been a vociferous advocate for learning to code – what we once used to call programming – in education. With Swift Playgrounds on iPad and related teaching materials, Apple has provided excellent tools to support this. Armed with an inexpensive and ubiquitous iPad, Apple’s free app, and the free iBooks, the next generation of developers have a near-perfect start.

What worries me is what becomes of them when they want to graduate to building ‘proper’ apps.

When I started writing software for the Mac, Apple’s documentation was exemplary. Substantial print books in the Inside Macintosh series, written by specialist authors in close association with Apple’s engineers, detailed and exemplified almost every last nook and cranny. Most importantly, they explained architectures, systems, how Mac OS worked, and how to get the best out of it in your own code.

Support engineers also wrote extensive example apps, which were freely distributed to developers. When Apple started to sell CD-ROM drives, which everyone thought wouldn’t catch on, it distributed Developer CDs containing electronic versions of documentation, example code, and full-blown demo apps.

I quickly became involved in Apple’s pioneering class library, MacApp, using it to develop a suite of CAD/CAM tools. MacApp wasn’t as well documented as Mac OS, but was supplied as source code, and built by those who used it. If you wanted to know how to support Undo in a command like Cut or Paste, all you had to do was read the source for MacApp’s built-in implementations of those commands. And when you found a bug, you could work out how to fix it and correct it in your source.

This last week, I have been working with some of the core code within Cocoa, in a part of AppKit (providing a wealth of services to apps) which works with text views, NSTextView. Since its development in early versions of Mac OS X, Apple has kept Cocoa’s source closed and strictly proprietary, making developers heavily reliant on its documentation and sample code.

Until about 2014, Apple maintained several detailed guides to NSTextView and its relatives. Although far from being fully explicit or complete, those were systematic and professionally-written. For example, the top-level Cocoa Text Architecture Guide explains most of the key concepts and how they fit together. It was last updated in February 2014, and at the top is now emblazoned:
Important: This document is no longer being updated. For the latest information about Apple SDKs, visit the documentation website.

When you follow the link to Apple’s new documentation website, you discover that no guides are now provided, and where they are still referenced, they are old archived versions. Instead, there is terse and largely automatically-generated listing of all the functions and other features of classes. If you know what you’re looking for, it isn’t hard to locate, but if you are trying to work out how to do something, Apple’s new documentation is next to useless.

Apple used to provide the source code of TextEdit as its prime illustration of how to use text in AppKit. The last available source to that app dates from February 2012, featuring changes made for OS X 10.7 Lion. Of course that is coded entirely in Objective-C, as Swift didn’t appear for another couple of years.

I have spent quite a lot of money buying print and iBooks which claim to detail the use of Swift in macOS development, and have a front row of five, together with another three which rely on Objective-C but have more extensive coverage of Cocoa.

So armed with no source code to NSTextView, out of date guides which are now replaced by terse and unhelpful class references, eight expensive third-party books, and completely out-of-date example code in a language which I don’t code in, I needed to work out how to perform a live word count of the document being edited in an NSTextView.

Judging by the books and other references, I must have been the first person on this planet to want to do that. Online search yielded a few very unhelpful references to the same problem in iOS – its equivalent of AppKit being UIKit – but it occurred to me that the built-in spell checker performed a word count, so I tracked that down using the third-party documentation browser Dash (which Apple evicted from the App Store some time ago).

The next question was how to get that count updated whenever the user edited the text. Some clues were given in the old guides which Apple has now archived that I could achieve this using a notification. After more scrounging around and imaginative guessing, I arrived at a simple solution: I made my ViewController class an NSTextViewDelegate and added a notification for its text changing which obtained an updated word count from
theCount = NSSpellChecker.shared.countWords(in: self.textView.string, language: nil)

None of this is discoverable from any of Apple’s current source code, documentation, or example code, and my solution relied on inspired guesswork.

So what happens when all these young coders are ready to start writing their first proper apps using AppKit? They are going to see this complete void in documentation, the absence of guides, example code, even online ideas, and wonder why they wasted all that time playing with Swift. Not only that, but when they get the hang of something like this in AppKit for macOS, they’ll discover that the iOS equivalent, UIKit, doesn’t support what they have just discovered, and they’ll have to go back to square one if they want to write equivalent code for iOS.

Maybe they’ll just use their coding skills to go off and code for Windows, or even Linux where at least they can always read the source.

Documentation isn’t just about providing today’s developers with the information that they need. It’s about all those new coders enthused with Swift Playgrounds, who will shortly find themselves in Apple’s information void.