The craziest thing I discovered from the inside is that there are gigantic swathes of fundamentally critical technology that lack even internal documentation. It was a regular occurrence that I’d have to ping the people who wrote some important bit of the media pipeline to get an annotated header or even just a couple of hours of explanation.
ETA: I got considerably more assistance from tab completing method names in PyObj-C than I did from official documentation sources. It was insane.
Note that I updated the title in response to some comments on that other website, because it was misleading the discussion. Ended up being a hotter take than I actually intended!
Let’s not forget that not only function documentation is dying, but also (once) incredibly valuable Technical Notes all talk about Mac OS X Leopard as the latest thing.
I am not sure what this article adds. It’s a rant, but there are no concrete examples of bad documentation, no examples of Apple documentation that is well-done, no examples of what you were concretely trying to archieve and how the Apple documentations fails there. This could be a nice analysis, bit I didn’t learn much beyond the title (except that apparently Ember.js documentation is good and Rust policy requires documentation of every symbol).
This stack overflow thread of sample Apple Watch code which hasn’t worked basically ever is an excellent example https://stackoverflow.com/questions/46086536/apple-sample-code-for-watchkit-extension-background-refresh
Not at all involved with apple stuff, but I found https://nooverviewavailable.com/ a neat idea (via https://atp.fm/episodes/349 )
Yes! I meant to include that in a footnote in the post! Editing it in now; thanks for the reminder!