Apple, can we please talk about your documentation?

You can do better than vast swathes of undocumented code, old samples, and incomplete WWDC videos.

Paul Hudson    November 23rd 2017    @twostraws

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.

Don’t believe me? Try reading the docs for NSCoreDataCoreSpotlightExporter, but prepare for disappointment. Or you could read NSPersistentHistoryResult, but don’t get your hopes up.

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.

Sponsor Hacking with Swift and reach the world's largest Swift community!

Four mitigating factors

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.

Can this be fixed?

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:

1. Could Apple please hire more writers? I realize for many things that’s a non-trivial task, but we’re not talking about major documentation rewrites or complex sample code. Instead, maybe just hire some junior folks to look at analytics, figure out which “No overview available” pages get landed on the most, and help make a prioritized list for the main writing teams to look at?
2. Could Apple look at ways to transfer code comments into their main documentation, at least where there is currently no overview available? Sometimes these comments are all we have, and could really do with more exposure.
3. Could Apple open source their documentation effort, or at least accept contributions from the world? I’ve suggested this in the past, and have offered to contribute and I’m sure there are hundreds of others willing to do the same.
4. Could they at least give us back the old-style API diffs, so we have one central repository for seeing what’s changed? The new documentation design is beautiful, but extraordinarily clumsy when you’re trying to work through dozens if not hundreds of changes.

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.”

Sponsor Hacking with Swift and reach the world's largest Swift community!