Reimagining Apple’s documentation

Example code, faster navigation, and goodbye to No Overview Available.

Paul Hudson May 7th 2021 @twostraws

For a number of years my #1 WWDC wish was that Apple would do something to dramatically rethink its approach to developer documentation. I still hope WWDC21 will be The Year When Something Big Happens To Apple’s Documentation, but rather than just wave vaguely and say “I want better docs” I figured I’d write down some specific thoughts that have been rattling around in my head.

I have a simple mental metaphor for what I want, which is this: what would happen if the hardware team who designed iPhones and iPads were asked to build developer documentation?

I don’t mean “make them describe thousands of APIs,” but instead I mean their mentality – the primary reason most of us buy so many Apple devices is because they are loved down to the micron level. Every tiny part of my iPhone, my iPad, my Apple Watch, and more has been thought about and made as good as they can possibly make it, from the screen, to the audio, to the battery, and beyond. The result is that the finished devices just feel fantastic even many years after they were released.

So I use that as my yardstick: what would magical documentation look like?

I’m going to outline my answers below, but honestly the conclusions won’t surprise anyone: getting fantastic, world-leading developer documentation isn’t about fancy new approaches to tutorials or interactive experiences, but almost entirely about finding the fastest, simplest ways to solve developer problems effectively.

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

TL;DR

Short on time? Fine – here’s the bulleted list of what I wish would change:

The top 500 most popular APIs (measured by page views) should have example code attached, ideally several examples with headers clearly marking what problem is being solved.
The top 100 most popular APIs should get either a screenshot or a video showing exactly how it works and what the result is.
Any place where header files have documentation comments and their matching online documentation is “No overview available” should have the header docs copied straight online.
No APIs mentioned in the WWDC Platforms State of the Union talk should be allowed to ship with “No Overview Available” as their documentation – either can the feature or prioritize documentation.
Link directly to relevant WWDC videos from API pages, ideally to precise timestamps. Even better, make sure everything mentioned in those videos gets included in the text documentation too.
Reinstate old WWDC videos that have been deleted.
When shipping major new APIs such as SwiftUI, Combine, and RealityKit, accompany them with learning courses similar to my own 100 Days of SwiftUI.
Add some gamification, allowing users to take tests to ensure they’ve learned a topic and earn badges on completion.
Provide quick links to key frameworks, then inside that provide quick links to key topics.
Make 404 pages show closest search matches.
Resurrect and refresh the classic API diffs.
Provide clearer, more detailed explanations of all Swift language changes.
Encourage Swift Evolution proposal authors to include simple, “before and after” introductions.

Does Apple need to do all of those? Of course not, but I hope this at least provokes some discussion.

Before we start…

Before I start I want to mention four important things. If you read anything below that seems to contradict these it’s my mistake and I should correct it, because they are really the fundamentals of what I believe.

First, there must be no compromise on privacy. None. When you visit Hacking with Swift there are zero trackers, zero analytics, and zero ad networks. Heck, even my server doesn’t keep logs of pages visited. I believe people come to my site to help them reach their goals with Swift, not to be tracked, and I know Apple’s teams feel the same way.

Second, Rene Ritchie tweeted about the idea of Apple running macOS on iPad, and I loved the way he boiled it down almost into a Venn diagram:

Why do you want macOS on iPad? Hold that thought! What percentage of the market do you really represent? Hold that thought! What would it take for macOS to work amazing on iPad? Hold that thought! What could Apple do that’d be better for more people on iPad?

I’ve tried to follow a similar Venn diagram approach: why do I want a particular documentation feature, what percentage of other people would want it too, what would it take for Apple to make it amazing, and would it really be better than what they have right now?

Third, I’m not naive: I recognize some of the things here would require significant effort, and I’m sure Apple has already considered some or all of them already – their developer publications (devpubs) team is packed with smart people, after all. However, I don’t think it’s fair for me to stand on the sidelines saying “give us better documentation” without at least being specific about what I mean.

And fourth, I need to acknowledge that there are a whole bunch of ways I could make my own site better. Believe it or not everything you read on Hacking with Swift, the entire site, all the videos, etc, are all created just by me, and honestly that doesn’t scale well. That deserves its own article, though, so for now just trust me: I know things need to improve here too, and I’m on the case.

Anyway, enough preamble – let’s get into some specifics…

Give us examples

If I could change Apple’s documentation, I would work to ensure it has many more examples than it has right now – hands-on sample code snippets showing a specific API in use. It is not enough to describe what a particular piece of code does, because most of the time that doesn’t tell us enough information to actually use it.

So, I would pick a number and use that as my benchmark: the top 500 most popular APIs must have example code attached. “Popular” doesn’t need to be anything special – I know Apple has its own site analytics in place already, but even just anonymous adding 1 to a counter every time a page is loaded gives a simple counter of what pages folks visit.

That alone would make our lives easier, because it would mean landing on a page gives a brief explanation of what it does, any extra usage notes, then practical examples – yes, examples is plural, because for particularly popular pages I want several, ideally placed under dedicated mini-headers for each problem being solved.

So, the top 500 pages get at least one example, with the top 100 of those getting either a screenshot or a video showing exactly how it works and what the result is.

That might sound like a big ask, but even PHP manages it – they have one or more practical examples of almost every function on offer, and even have user comments providing extra detail. I realize that Apple is unlikely to want to add user comments because it would be beyond their control, but it’s past time to make example code a priority.

Syncing with header files

One of the most frustrating problems Apple faces with their documentation is that someone, somewhere is writing really comprehensive code documentation that isn’t being synchronized with their site.

For example, here is the online documentation for SCNAnimation in SceneKit. That class, as well as all properties of that class, greet you with “No overview available” – no guidance even on what it does, never mind how to use it.

In comparison, if you’re in Xcode and press Shift+Cmd+O to bring up Open Quickly and look for SCNAnimation there, you’ll find comprehensive in-code documentation right inside the auto-generated Swift interface – every property is explained, including usage notes, default values, and more.

So, if I could change Apple’s documentation I would say “if our online documentation says no overview available but we have documentation comments, copy them wholesale into the online docs.” Sure, if there is time I would want to add more detail, but set an absolute baseline that if the documentation is good enough to ship with Xcode it’s good enough to put on the Apple developer site. Presumably those comments in Xcode haven’t been given the DevPubs Seal of Approval™ or something, but honestly something’s got to change.

Regularly being faced with “No overview available” is deeply frustrating for me, and I’m not alone: as Casey Liss pointed out it was over a year before Apple provided documentation for compositional collection view layouts, despite a) them having remarkably detailed comments in Xcode’s header files, and b) them being a huge new feature in iOS 13.

And that’s brings me on to my next topic…

Making more of WWDC

If I could change Apple’s documentation, I would set a new rule: no APIs mentioned in the State of the Union talk (SOTU) are allowed to ship with “No Overview Available” as their documentation – you either get more people on board to document the feature or agree it’s not a priority.

Every year Apple introduces thousands of new APIs for us to work with, and if everything is a priority then nothing is a priority. But at the very least surely we can agree that if Apple’s top engineering brass go on stage Monday afternoon to show off the greatest new features, the least they can do is make sure there is also documentation available for them?

Apple puts a lot of work into creating its WWDC videos, and it’s no surprise they are extremely high-quality resources. But then what? Honestly, they kind of disappear, which is odd – for many APIs they are literally the only meaningful documentation we have.

So, if I could change Apple’s documentation I would do two things: link directly to relevant WWDC videos from relevant API pages, ideally to precise timestamps, but then I’d also make sure all the content in those videos is available as text for the many people who prefer written documentation.

I would also revert Apple’s behavior of deleting old WWDC videos – I’d bring them back into a huge archive that’s easy to search and browse. You might wonder what value old WWDC talks have, but some of my absolute favorites have disappeared – “Building Better Apps with Value Types in Swift” by Doug Gregor and Bill Dudney is an absolute classic, as are “Prototyping: Fake It Till You Make It” and “A Strategy for Great Work”, but these seem to have been erased from history.

But I would go a step further: when something major is announced, such as SwiftUI, Combine, or RealityKit, I want to see Apple make a course helping folks learn it – something that really puts the technologies into a practical context. I myself have done with this with the 100 Days of SwiftUI, but wouldn’t it be incredible if Apple did that themselves – if Apple were able to create a hands-on curriculum, backed with both text and video, helping folks get into major new frameworks or updates, and available on day 1?

Then I would go one step further still: to help folks track their learning over time, I would add a touch of gamification. If you’ve been through my 100 Days of SwiftUI course you’ll know there are dozens of quizzes that help you double check you’ve understood what was covered, and if you’ve used my Unwrap app you’ll know it remembers what you learned and unlocks badges as you achieve milestones.

I don’t want to detract from the more serious side of helping developers get the most from Apple’s frameworks, but at the same time it’s critically important to welcome more and more people into our field and that means making learning accessible and vibrant.

Finding things more easily

I mentioned I ran a poll asking folks where they went to learn how to use a new API, and there 29% of people said they visited Apple’s online documentation. So, where is everyone else going?

Well, just short of 50% of people said they visit a third-party site to learn about Apple’s own APIs, which really ought not to be the case. So, if I could change Apple’s documentation I would do several things.

First, I would prioritize making it easier to find key frameworks, specifically UIKit, SwiftUI, Combine, Foundation, and similar. Right now the homepage has a huge animated header, then top stories about making custom SF Symbols, creating Smart App Banners, and using ProRAW.

These are interesting and important topics, but if you’re one of the 99% of people who just came to work with one of Apple’s core frameworks you need to click the small Technologies link in the top right, then either scroll or filter for UIKit.

Second, I would make it easier to navigate straight to important pages. I don’t know about you, but I browse Apple’s documentation by typing precise URLs – I type https://developer.apple.com/documentation/swiftui/ followed by whatever thing I’m looking for, such as https://developer.apple.com/documentation/swiftui/navigationview, because otherwise I need to scroll through Apple’s categories and figure out where something is.

If Apple approaches its APIs from the point of view of a parent towards their children, then all APIs are beautiful and deserve equal support and encouragement. But honestly how often do look up parts of UIViewController, UIStackView, or NSLayoutAnchor compared to how often you need to look up parts of UIPencilInteraction, UIPrinterPickerController, or UIPreviewTarget?

Putting these together would mean organizing the homepage of https://developer.apple.com/documentation around getting fast access to the most commonly used information: if you’re landing here you’re probably looking for one of these five or six frameworks, and if you’re interested in one of them then chances are it will be one of these ten types. All this would live alongside the current categorization they have – I want to add to that rather than replace it, and to feel confident that I can find an article faster through following links than I can by trying to type exact URLs.

But, once again, I would go a step further: I would make their 404 page include search results.

Here, try these two URLs:

The first link is my site, and because the URL doesn’t exist I automatically run a search to help you find what you wanted. It’s not perfect, but it does at least help you get to where you want to be: either the page you intended will be listed in the results, or you might find a different page that interests you. Plus, folks who know this exists can use it for faster access to the site.

The second link is Apple’s developer documentation results, which tells you the page doesn’t exist and offers a search box. What are you going to put in that search box? Well, probably what you just typed the URL, so how about we just skip that step and show the results straight away?

But there’s more. You see, Apple’s hierarchical API layout pages have a clever, but ultimately infuriating feature: in the top-right corner you can activate API Changes, which shows you whether one of the sections or pages has had things added, removed, or modified in a recent Xcode change. For example, here’s the link to see the latest minor changes for SwiftUI.

Obviously this changes with every Xcode release, but right now it shows almost every section has changed, and if you select any of those, such as Views & Controls, it shows almost all the text, buttons, controls, values, and value indicator types have all been changed.

However, if you dig even further you see the problem: Apple has fully deprecated some view modifiers that were soft deprecated in iOS 14.0, but thanks to the way Apple structures their documentation their system marks almost every part of SwiftUI as having changed, which is what makes this so frustrating – you want a brief summary rather than having to dig repeatedly and figure it out for yourself.

What we need is a way to figure out what changed across Apple’s frameworks, but what we have is a very beautiful, very frustrating nest of links that must be followed and examined individually. To borrow the words of Tony Hoare, “the clothes have no emperor.”

The thing is, Apple used to publish exactly this. Back in the old days they would release API diffs where you could select a single framework and see exactly which methods and types were add, removed, and modified, showing exactly what changed.

If you haven’t seen these API diffs before, there’s no need to wonder what they looked like because Matt Stevens publishes them even today – he wrote a tool to generate something almost identical to what Apple used to produce, and although it’s all in Objective-C rather than Swift it does at least tell you immediately what’s changed. For example, here’s Matt’s API diffs for UIKit, going from iOS 14.4 to 14.5.

As a workaround, I’ve resorted to running a small GitHub repository that tracks SwiftUI changes as a simple changelog on its generated interface file. This kind of thing is far from ideal, but right now it’s the only meaningful way to see what’s actually changed over time.

So, if I could change Apple’s documentation, I would find a way to resurrect their classic APIs diffs for a Swift-focused future. Yes, I realize they’d want to spend a long time producing a modern design and that’s important, but ultimately I want something that gets straight to the point with every platform update: here’s exactly what changed on a framework-by-framework level, with links you can click to find out more.

I can’t possibly finish this section without adding one last thing: dark mode? Please?

And finally… what’s new in Swift?

One of the biggest problems our community has faced for the last few years has been the ever-evolving nature of Swift itself. On the one hand Swift Evolution has been an incredible engine for change, bringing together highly talented compiler engineers with the real-world perspectives of app developers in our community. But at the same time, it’s caused a fairly constant language churn that means:

Many people find it hard to keep track of new Swift language features.
Many code samples, tutorials, and projects online are out of date.

The first of those doesn’t specifically cause a problem, because old-but-valid Swift still works.

But all this change created a side effect: so many presentations at conferences are focused on Swift language features as opposed to making great apps. I personally really enjoy these talks because I find core language changes can really affect the way I approach every kind of Apple platform development, but I know a lot of folks want to hear more about animations, performance, user experience, and more – things you can achieve just as well with Swift 1.0 or even Objective-C.

All the change has also meant lots of code samples are out of date, which in turn means sites such as Stack Overflow become problematic because you’re just as likely to see answers for older versions of Swift as you are to find something useful.

I do my best to tackle both these issues head on: I regularly release “What’s new in Swift?” articles that walk through the key changes in each Swift update along with copious code samples, and even host https://www.whatsnewinswift.com so you can compare all the changes between any two versions. I also spend a lot of time updating my Swift Knowledge Base, which is home to over 600 code samples across Apple’s frameworks, plus SwiftUI by Example, which is home to another 300 code samples specifically for SwiftUI, all so that folks who land on my site can feel confident they are getting the latest information available.

Apple might look at that work and think, “why bother talking about Swift updates when the community already does it?” I hope not: having a plurality of community voices is important and I want that to continue, but there’s still a lot of scope for Apple to provide detailed documentation beyond just linking to a bunch of evolution proposals.

And if that isn’t possible, at least make it a requirement that – as far as possible – Swift Evolution proposals get straight to the point with a practical “before and after” introduction: here’s what you write now, and here’s what you can write with this change in place. As an example of what I mean, compare the Swift Evolution proposal Extend implicit member syntax to cover chains of member references with my own discussion of the same change.

Now what?

Some might read this article as a series of complaints, and if that’s how it comes across please accept my apologies. I have tweeted in the past how much I appreciate the work Apple’s devpubs team does, and honestly I know they are doing their best.

In fact, I almost feel guilty asking them to do even more, because I have no doubt they are already pushed to their limits. Instead, I guess what I’m really arguing for is a serious increase in their funding so they can tackle these new areas.

I have no idea whether anyone from Apple will read this article, or if they do whether they would take any of my suggestions on board. Of course, there’s a really high chance they’ve already talked about everything mentioned here, but regardless I am clinging to my hope that this year will be the year Apple dramatically rethinks its approach to developer documentation.

I want documentation that is detailed, that is hands-on, and more than anything is prioritized, and given how much money the App Store produces I honestly think we deserve it.

Anyway, I intended this article to be nice and short and it grew into quite a bit of a rant of me telling other people how to do their job. Thank you for your patience – I hope you can understand I’m writing this from a position of deep appreciation for the work Apple’s devpubs team does, because if I didn’t care at all I wouldn’t have even bothered writing all this.

So, thank you, devpubs: I know I’m asking you to do more work, but really what I’m asking for is your management to provide you with the extra time and resources to make something magical we can all benefit from.

After writing this, I wrote a second article focusing on what I think needs to change on Hacking with Swift, and you can find it here: Reimagining Hacking with Swift.

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