For the last year or two, I’ve come to realize that the number one thing that makes it harder for me to do my job is documentation. Or, more specifically, the utter dearth of documentation that Apple provides for its platforms.
As a developer, Apple provides us a series of tools — APIs — that allow us to make apps on iOS, iPadOS, macOS, and tvOS. In many cases, it’s fairly straightforward to figure out how to use these APIs. There’s only so many ways you can use a screwdriver, and similarly, in many cases there’s only one obvious way to use an API.
However, as users rightly demand more complicated and fancy apps, the APIs often need to get more fancy and complicated as well. Suddenly you look up and, instead of only using screwdrivers and hammers, you’re using power tools and complicated saws, and everything is much more fiddly than it once was.
With real power tools, you expect to receive an owner’s manual, which explains how to use the tool you’ve just purchased. A rough analogy exists for APIs, insofar as most platform vendors will provide documentation. This is basically the “owner’s manual” for that API.
Apple’s documentation has, for years, been pretty bad. Over the last couple years, it has gone from bad → awful → despicable → embarrassing. All too often, I go to research how to do something new, and use an API I’m not familiar with, only to be stymied by those three dreaded words:
No overview available.
This is Apple’s way of saying “Fuck you, figure it out”.
No overview available is so bad that a popular Apple resource — itself something that probably shouldn’t have to exist — used it as its namesake for a single-serving site to highlight how bad Apple’s documentation is.
The march of progress doesn’t help, either. As my friend Adam Swinden pointed out to me on Twitter, as old APIs get deprecated, often times Apple can’t be bothered to include documentation for the new ones. Check out the difference between this API and the one that replaces it.
No overview available. Fuck you, figure it out.
A couple years ago, two new phenomenal APIs were introduced around
UICollectionView:
For at least a year — maybe two — far and away the best documentation for these new and important features was hidden in the header files. That’s despicable.
On this week’s Under the Rader, my pals Marco and Dave continued their arc of Marco’s transition into Swift and SwiftUI. In the episode, both Marco and Dave really eloquently described some of the absolute pain Apple developers go through in trying to understand how to use the tools Apple provides.
At the bottom of this post is a transcript of their thoughts, which has been lightly edited to make things a little more clear for the written word. Overcast timestamp links are provided at speaker transitions, if you’d like to listen to it from the horse’s mouth.
No matter what, I’ve been banging on this drum for years. I haven’t a clue what the problem is at Apple.
- Is the documentation team not given the time to react to new APIs? (I’d buy it.)
- Is the documentation not considered a prerequisite for shipping? (I’d definitely buy it.)
- Is the documentation team really bad at their jobs? (I doubt it.)
- Is the documentation team too small? (Likely.)
- Is the documentation team stymied by politics or in-fighting? (Probably.)
Whatever the problem is, it needs to be fixed. This is a problem that has been festering for years, and the pot is finally boiling over.
Under the Radar Transcript
Marco: Having to learn SwiftUI is, first of all, the learning resources out there are still terrible, because it’s such a young language/framework/method of even thinking about things. It’s so young, and it changes so frequently — similar to the early days of Swift — that a lot of the tutorials, sample code, or Stack Overflow answers that are out there are no longer even correct. Because something has changed since when they were written last year, and now. Or the answer was posted during a beta, and in a later beta even that same year, the name of a class changed, or the way you’re supposed to do something changed. It’s so early, still.
This is a time when you really feel how much we need better documentation support from Apple. One of the great things […] about PHP 🤣 is that PHP has always had exceptional documentation on its website.
On php.net, you an search for any function, and editors would build in hotkeys so, in Textmate, I can hit ⌃H and it pops up a documentation window from php.net about whatever function name I have my cursor on at that moment. There’s always been great documentation there. On the documentation pages — in almost every function in the language, which is a lot — there are example code snippets on documentation pages. And there’s comments! So even if the example code doesn’t quite there for you, or doesn’t answer a quesion you have, the comments usually do.
This is something that I really wish Apple’s documentation would have — these little usage examples — because they really can help explain and show, better than just a pure API reference, how to do something. Or what a function is for.
As we move into the land of SwiftUI, and Combine, and all of these higher-level concepts, a little more complicated things — this is also going to apply similarly once Swift gets its whole async/await thing, presumably in a year or two. It becomes harder to understand a lot of these concepts, because they’re so abstract, and they have really simple-sounding names, and it’s really hard to tell what this does, how to use it, and so we all end up having to go to StackOverflow, and tutorial blogs, because Apple’s own documentation — [if] it’s even there, and that’s a big [if] — is so bare-bones and minimal, it’s like Jony Ive designed it —
Dave: …it’s a big white room…
Marco: Yeah, it’s a big, white, empty page. And it’s like, “this type is to do this one thing”, and then there’s no other context; no example showing “when would you use this”, “how do you use this”, “do you call this in a certain way, like as a constructor”.
You can get so much value out of those little tiny snippets on documentation pages, like what PHP does. Like, “here’s a four-line example of how to use this thing”. And I wish for that so much as I’m learning this stuff.
I’m seeing — and I would imagine this is how beginners see almost all parts of programming — because I am such a beginner at Swift and SwiftUI and at these concepts that SwiftUI is built upon — I’m seeing what it’s like to be a beginner for the first time in a while. I would benefit so much from better documentation, and to have — presumably at Apple — a pretty strong effort to not only write the documentation, but then to update the documentation as the language changes.
This is the problem when you have these young languages that are greatly in flux, or these young frameworks that are greatly in flux. If you’re relying on tutorial blog posts, and StackOverflow answers, well those go out-of-date pretty fast, as I was saying earlier. It’s nobody’s full-time job at Apple to make sure that all these tutorial blog posts that are out there can be updated when the language changes, so they mostly just aren’t [updated]. Or, some of them are, some of them aren’t, and it’s hard to know what you’re going to land on when you find it.
Even then, SwiftUI, for as cool as it is, and as much attention as it’s gotten from language nerds over the last year, there is very little out there about it; there is very, very little. There’s even less out there that goes beyond trivial use cases. For instance, if you have to make a tech demo with SwiftUI, and you have to have a button state that changes, and increments a number or whatever, great! There’s a million blog posts out there about that.
But then, once it’s like, “Okay, how do I tie this into the rest of an app?” That’s a real app, that has actual needs like persistent storage, different screens, and everything. Once you add the complexity of real-world apps, most of these tutorials can’t cover that, or don’t cover that. So, I’ve had such a time, Dave, trying to adopt SwiftUI from these trivial little tutorials that people have, or that Apple has in WWDC sessions, to try to actually build “How do I connect that to my database”? “How do I connect that to my downloader or my sync engine”? There’s been so much of that. And I think I’ve finally got it, but man is it non-trivial and non-obvious, and there’s so many weird little pitfalls.
Dave: I absolutely feel your pain, though. What’s so frustrating to me about this […] there are absolutely a couple of really tremendous SwiftUI resources online. For me, it’s Hacking with Swift by Paul Hudson. Like 80% of my SwiftUI knowledge has come from his site, and his videos. […] He has this great process where he’ll make these videos that show you one level beyond the trivial example, where you end up with something that’s like… Trivial+. It’s not a full-blown example, […] there’s still those rough edges that you’re talking about. I definitely continue to run into that. Where I want to do something a little bit more than the obvious case, and then, it’s like you’re jumping off this cliff, and it’s like “good luck”. […]
I remember back at the beginning of the spring, I remember there were a couple of the educators in the Apple community. People who are typically on the conference circuit, they speak at a lot of the conferences, and they do workshops, and educators like that. And they were saying “You know what? We’re not going to able to travel for all of 2020, it seems. We’re not going to be able to do conferences; we’re not going to be able to do a lot of things. Hey, Apple, There’s a lot of really talented educators in your community who have a lot of spare time. It’d be a great thing if you took advantage of that.”
It’s kind of sad that now that we’re sort of toward the end of the year, it doesn’t seem like they did. It doesn’t seem like there was any kind of movement on that, to leverage all of these people who are excellent at explaining things, at creating example apps. At doing this work in a way that would help people in your circumstance, in my circumstance. I really feel for the people who are coming at SwiftUI without decades of programming experience. If this was the first app you’re learning, in some ways it’s easy-ish. […] A really basic SwiftUI app is really easier to build, probably, than the most basic UIKit app. But, as soon as you start getting beyond that, it gets so complicated so quickly.
I also think of how — it’s so difficult with documentation — is how, the people who are best able to make documentation for a new platform are the people who make the platform. Because they can work on the documentation, and have it available at the process of it being released. […] I feel bad for all the Apple tech educators, [when] a new SDK drops, or a new beta releases, and then they’re just like, not-sleeping for three days trying to frantically update all their stuff, and get new stuff covered. They do a great job — and I appreciate it — but this doesn’t have to be frantic.
This could be, the documentation team at Apple has been working on this in concert with the people writing the APIs for months. So on day one, here’s a great set of examples, that show code about how to use this.
You’re exactly right — especially about SwiftUI — the nature of it is that traditional documentation… If you go to the documentation for Text in SwiftUI, the View, the number of different modifiers you can apply to that View is probably in the hundreds — if not more. But, having just this gigantic list of all the things you could possibly ever do to a Text isn’t helpful. What you want to see is, “Okay, how do I do text that looks like this?” “What if I want multiline text?” “What if I want multiline text that has only this many lines, and then is aligned in the middle?” Doing that kind of stuff, you need examples. I don’t think the total number of cases that people actually use is that wide. I feel your pain.