You can do better than vast swathes of undocumented code, old samples, and incomplete WWDC videos.
Every year Apple wows us with hundreds if not thousands of new APIs to deliver increasingly amazing apps to our users.
Sadly, though, their documentation team is struggling to keep up: at the time of writing, just over 15,000 pages of Apple documentation have “No overview available” as their description, the overwhelming majority of sample code hasn’t been updated for Swift 4, and even more new APIs are still being released so the situation is just getting worse.
Or there’s UICollectionViewFlowLayoutSectionInsetReference, UITextDragPreviewRenderer, VNImageOption, MKMapItemTypeIdentifier, SCNAnimation, and HMCalendarEvent. I mean, wouldn’t it be nice if the documentation for kLAErrorBiometryLockout actually described when it might occur?
Oh, you want to make HealthKit apps? Good luck using HKWorkoutRoute. Or how about HKMetadataKeyInsulinDeliveryReason, which sounds so important that it surely that must be documen— oh. And HKBloodGlucoseMealTime? That gives you the (undocumented, natch) values “postprandial” and “preprandial” - how’s your Latin?
And how would you feel if I said all those APIs were introduced on or after iOS 11.0?
Maybe you’re lucky. Maybe you only make macOS apps, in which case you’re in great shape! Just kidding: NSWindowTab, NSWindowTabGroup, NSAccessibilityAnnotationPosition, NSFontAssetRequest, PHProjectType, NSBindingOption, NSAccessibilityCustomRotor, NSAccessibilitySortDirectionValue, NSFontDescriptor.FeatureKey, and many more send back “No overview available”.
(And yes, all those were introduced on or after macOS 10.13.)
Or maybe you’re unlucky. Maybe you’re trying to work with AVFoundation, which is a hugely important framework to Apple developers, where documentation is apparently rather hard to come by these days. Again, all those were introduced on or after iOS 11.0/macOS 10.13, although this is not a new problem.
Of course, it’s also possible you kicked a karmic kitten in a previous life, and you’re forced to use WebKitJS, which is a huge framework that almost has less documentation than this article you’re currently reading.
This is something I’ve complained about previously (and then some!), but the situation seems to be deteriorating – some sources have said the problem is that recently Apple diverted many members of its documentation team to work on Swift Playgrounds, which would be frustrating if true.
There are a few mitigations worth mentioning here.
First, some of these APIs you can figure out either with guesswork, with a dictionary (postprandial? really?), or with specialist knowledge. This is undoubtedly true, but it’s both a huge waste of time and hugely off-putting – it’s mentally exhausting trying to fight your way through APIs to use a new feature when many if not all of them are undocumented. And even when you do figure out what something does, you’re often not entirely clear on why it works that way or how it fits into the bigger picture, which is a critical part of any documentation.
Second, Apple often discusses its new APIs at WWDC. The new SceneKit animation framework, for example, got a special call out during the “What’s new in SceneKit” session at WWDC17. It is of course woefully documented: both SCNAnimation and SCNAnimationPlayer come back with “No overview available”, as do every single one of their properties and methods.
Worse, Apple relies heavily on WWDC magic: it’s common for them to show you only part of code samples, where helper code to make things actually work is missing. When this code is then not made available for download – which is frequently the case – then the video is nearly useless. In the past I’ve had luck emailing Apple engineers directly and they have shared their WWDC code with me under the condition that I don’t distribute it further, but this shouldn’t be the case.
Third, frequently you’ll find that Apple’s development team have inserted comments into the header files for their work. These take a little more work to find because you need to jump between their code and yours, but it can often be the difference between having a vague idea of what you’re working with and being faced with a completely blank canvas.
These code comments also suggest that the development side of Apple is taking documentation more seriously than the documentation side of Apple, which is a remarkable situation to be in.
Fourth, sometimes Apple does get documentation right: I’ve called out instances in the past where Apple’s documentation has been comprehensive and it’s made a huge difference – the Touch Bar docs were actually great from launch.
Now, I don’t want this post just to be a list of complaints. I know Apple’s writers aren’t sitting around bored all day, and I’m sure that many of them feel just as frustrated as I do about the current state of affairs.
So, let’s look at some possible solutions:
Now, even though some could argue I have a vested interest in Apple’s documentation being full of holes (I write books teaching Swift development on Apple’s platforms), I genuinely want this situation to improve.
If there were a way that I could publicly contribute to Apple’s documentation I would – I promise you – jump at the chance. This is partly because when I write books for all-new Apple technology I’ve been through the pain myself and don’t want others to have the same problem, and partly because basic economics says that if I help grow the ecosystem it benefits me too.
But the main reason is because so much of my life is spent working with the output from Apple’s development and documentation teams, and I want to do what I can to contribute back – even if that’s something as minor as migrating their existing sample code to Swift 4, or copying and pasting code comments into online documentation.
Anyway, enough of me ranting. This problem has been brewing for a long time, but I hope someone at Apple can point at this post and say “we need to do better.”
Me: Where’s the documentation for this SDK?— Ellen Shapiro (@designatednerd) September 27, 2017
SDK owner: The code is self-documenting!
Me: …so there is no documentation?
When I ask myself "what would have the most impact today?" I sit down and write documentation.— Miguel de Icaza (@migueldeicaza) December 12, 2015
Paul Hudson is the creator of Hacking with Swift, the most comprehensive series of Swift books in the world. He's also the editor of Swift Developer News, the maintainer of the Swift Knowledge Base, and a speaker at Swift events around the world. If you're curious you can learn more here.
Link copied to your pasteboard.