Published in News

Apple’s documentation is missing

by on30 October 2019

A developer has even looked at the back of the sofa but there was nothing

Developer Chris Krycho has attracted a fair bit of attention for pointing out that parts of Apple’s software documentation is non-existent.

Writing in his bog Kyrcho said that for a few months he had been trying to get up to speed on the Apple developer ecosystem, as part of working on my rewrite project. This means he has been learning Swift, SwiftUI, and iOS and macOS APIs.

He said that Apple’s ecosystem has holes which are entirely undocumented and “shocking”.

To put this into some perspective, Krycho spends most of his time working on JavaScript front-end application development world, working in first AngularJS and then Ember.js. In other words he is used to working in the real software development world where things are done pretty much professionally and developers can write code to tell the time.

He said that Ember’s docs once had a reputation of being pretty bad, but in the four years he had been working with it, it had gone from decent to really good. "On the other hand, when I was working in AngularJS 5 years ago, I often threw up my hands in quiet despair at the utter lack of explanation (or, occasionally, the inane explanations) of core concepts.

“I thought that would have to be the absolute worst a massive tech company (in that case, Google) providing public APIs could possibly do.”

Then he looked at Apple’s documentation.

“I was wrong. The current state of Apple’s software documentation is the worst I’ve ever seen for any framework anywhere”, he said.

Most of SwiftUI is entirely undocumented — not even a single line explanation of what a given type or modifier does. Swift Package Manager has okay docs, but finding out the limits of what it can or can’t do from the official docs is difficult to impossible, he reckoned.

“ I’ve repeatedly been reduced to searching through WWDC video transcripts to figure out where someone says something relevant to whatever I’m working on,” he wrote. “I understand that Apple’s API developers (often) work in a different context than these open source projects — especially in that they face crunches around releases which are tied to hardware products shipping. But when you’re vending an API, it isn’t done until it’s documented. Full stop.“, he said.

He told Jobs’ Mob if it want sdevelopers to love their platform and don’t want them to flee for other platforms then they needed to take this seriously.

“Adopt the mentality that has served other frameworks and languages so well: If it isn’t documented, it isn’t done”, he wrote.

Last modified on 30 October 2019
Rate this item
(1 Vote)

Read more about: