Hacker News Reader

Comment by jph | Hacker News Reader

This Apple ExtensionKit documentation page opens with "Extensions are executable code bundles" but doesn't provide any executable code bundles such as examples, doesn't provide any way for a developer to ask a question, and doesn't show how a developer learns to create an extension.

This misses opportunities to reach developers-- and the tech is actually really compelling. I'm experimenting with it in the BoldContacts app, which conceptually extends the Contacts app to give disabled people ways to contact their families and caregivers.

Apple's documentation group needs a new leader ASAP who can emphasize documentation usability in concert with real-world developers. Apple wants its platform to continue being successful, and this goal can be helped by a documentation team that creates examples, questions-and-answers, and tutorials.

View on HN

Totally agree.

Apple’s API documentation is nearly useless because it usually doesn’t give me any info that I can’t already infer from my IDE (which of course is XCode, sigh).

I usually don’t need a list of classes and methods, I need to know how the pieces fit together to do something useful.

They say a picture is worth a thousand words. Well, an example is worth a thousand method signatures.

Yes! To add to this, I also don’t want useful information buried in videos. I’ve run across things where the information I want is likely in a WWDC video that is linked from somewhere in the documentation full of method signature. I don’t want to have to watch a video to get what I could find much faster in some static form. It always confuses me when people see videos as a useful alternative to well written documentation: who on earth has time to sit through hours of videos just to figure out how to use an API? Transcripts help, but I find that they’re still not a replacement for well documented examples and walkthroughs.

I’ve been working on adding a watch companion app to an iOS app and its been maddening. The documentation boils down to: you can send strings back and forth. The method to sync app state doesn’t work in the simulator. It appears the rest is on my own to discover. I’m convinced its impossible to develop a watch app only using the simulator and docs.

> doesn't provide any way for a developer to ask a question

If you ask questions on the developer.apple.com forums, Apple engineers often answer them directly. At least that has been my experience.

I think this is by design. Apple wants to weed out non-loyal developers, so only the ones who truly love the platform build software for it. Unfortunately, it drives developers to use cross platform tech instead, which apple hates

> … doesn't provide any way for a developer to ask a question, and doesn't show how a developer learns to create an extension

Is this because programming that targets poorly documented APIs is taught at select universities, and Apple wishes for these new grads to have an upper hand?

Reply on news.ycombinator.com