On Apple's Piss-Poor Documentation (caseyliss.com) 123
Casey Liss: 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 tools, you'd 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 to awful to despicable to 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 the new ones can't be bothered to include documentation. Check out the difference between this API and the one that replaces it. No overview available. Fuck you, figure it out.
Apple's documentation has, for years, been pretty bad. Over the last couple years, it has gone from bad to awful to despicable to 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 the new ones can't be bothered to include documentation. Check out the difference between this API and the one that replaces it. No overview available. Fuck you, figure it out.