No Overview Available
It’s become a truism among iOS and macOS developers that Apple’s documentation is often incomplete or missing altogether.
But to what extent is this actually the case? With a bit of web scraping, I was able to come up with some numbers:
It’s the new “Description forthcoming.”
You have to look beyond the colors, and even the numbers. For example, HealthKit gets 100% for documenting 7/7 symbols. But if you click through this seems to be just a bunch of error symbols. There are actually 55 header files for HealthKit, each containing many symbols. In other words, the denominator is the number of symbols that are admitted to be undocumented, rather than the actual number of symbols.
But that doesn’t mean there’s no documentation for them. Many of the symbols have good doc comments in the headers. Yet despite Apple releasing HeaderDoc 19 years ago, it doesn’t seem to have an automated way to get those comments into the published documentation.
Previously:
Update (2019-10-21): Mattt Thompson:
Source code for NoOverviewAvailable.com is now available on GitHub[…]
Update (2019-10-25): Mike Zornek:
During the multiple discussions it has been suggested that this documentation issue is an easier problem for Apple fix than others since documentation can be produced in parallel, money can buy more writers and Apple has plenty of money.
This is mostly true, but a major factor that is not brought up is Apple’s reluctance to hire remote documentation writers.
[…]
There is a fixed, limited pool of candidates who live or is willing to relocate to the Cupertino area. It gets even more difficult when you consider a technical writer will probably make less (Glassdoor listing) than a developer and yet the cost of living out there is crazy for both professions.
See also: Accidental Tech Podcast.
Update (2019-11-01): Chris Krycho (via Hacker News, Slashdot):
The number of parts of this ecosystem which are entirely undocumented is frankly shocking to me.
[…]
The current state of Apple’s software documentation is the worst I’ve ever seen for any framework anywhere.
[…]
Given what I know of Apple’s approach to this, the problem is not individual engineers (who are not responsible for writing docs) or even the members of dedicated documentation teams (who are responsible for writing docs). But that does not make it any less a failure of Apple’s engineering organization. The job of an API engineering organization is to support those who will consume that API. I don’t doubt that many of Apples API engineers would love for all of these things to be documented. I likewise do not doubt that the documentation team is understaffed for the work they have to do. (If I’m wrong, if I should doubt that, because Apple’s engineering culture doesn’t value this, then that’s even worse an indictment of the engineering culture.) This kind of thing has to change at the level of the entire engineering organization.
Apple not documenting and providing unstable tools will push people to use cross platform and hybrid technology.
Why use native when the other tools are taking the heat for you and provide documentation?
I’ve even seen people pointing to documentation for Microsoft’s cross-platform stuff as being the authoritative source on how macOS works, because Apple’s own documentation on the topic is absent.
Some time ago, I was contacted by Apple to apply for a job. My code is insanely well-documented. I like to think that a lot of the inspiration for my code docs comes from Apple’s open codebases. Their code is exceptionally well-documented.
[…]
In any case, during the test, I did what I always do when I write code. I stopped to write a header document for the function.
This was clearly not something the tester liked.
When I was learning Cocoa, Apple’s docs were the best around. These days, it’s all left to rot in the Documentation Archive, and it’s much harder to find anything helpful for newer APIs. If this year’s meme helps Apple realize the damage they’ve done to their documentation, great
What happened to Apple’s docs? I think the biggest reason is Swift: Apple’s adoption of Swift as the language they want devs to think about instantly invalidated decades of great documentation and sample code. All new docs are Swift, all WWDC material is Swift, all focus on Swift.
This makes me so sad, because I felt like Apple had some of the best documentation and programming guides around before the ubiquity of iOS and stack overflow. If there was a hole, there was usually a good article on the topic as well.
Now, there are a ton of “beginner” resources, but almost no guidance on the more obscure APIs and frameworks
I feel like they could easily hire remote developers to document existing APIs without feature of leaks, just to flesh out undocumented things, and any new APIs right after WWDC starts and during the beta period.
There has been some discussion about Apple’s developer documentation being less-than-complete, and people have made remarks about the issue of moving to the Cupertino area as a drawback for potential authors.
But note: Apple is actually hiring in Seattle.
Whoa! The Accelerate page has been updated: every article and piece of sample code is available in one place.
Forget “No overview available” Apple’s code documentation has far worse sharp edges. This property is marked as iOS 11.0+. Guess what happens when you use it on iOS 11? It crashes because it doesn’t recognise it
6 Comments RSS · Twitter
Yeah, pulling comments from headers is a solved problem! I use doxygen for my FileView framework, and it even produces a documentation bundle that integrated with Xcode's documentation browser, back in the day. The Carbon headers were always far better at examples than Cocoa headers, though.
The old docs were formatted better, IMO, and I really miss the tableview. Why should I have to scroll horizontally in the middle of a page to see the declaration of -[NSString writeToFile:atomically:encoding:error]? It was also nice to have the declaration and parameter summary for all messages to a given class on a single page, instead of having each instance method be its own page.
@Adam Yeah, the new pages are so index-like that they’re not really worth skimming or in-page searching. So lots of clicking.
Thanks for pointing out the incomplete results for HealthKit. Turns out, the landing page for HealthKit has inexplicably different markup from the other frameworks, and that slight difference was enough to break my web scraper.
I just made the necessary fix, re-ran the scraper, and published a new build of the site with updated stats for HealthKit. It now reports 1011 / 1013 symbols to be documented, which is closer to what I'd have expected. I'll do the same for the rest of the frameworks over the weekend.
@Mattt Great! And it looks like I missed most of the HealthKit documentation myself. I’m used to scrolling to the bottom to see the full list of classes, and found very little this time. There actually are class lists for HealthKit, but they’re within section-specific subpages now. I miss those old pages that listed all the classes for a given framework all at once, so you could see how they fit together and also quickly find the one you wanted.
Let’s be clear. The state of the docs absolutely falls on the dev pubs department.
Why is Apple writing docs in Seattle?
Devpubs (as a department) should be in Apple Park, with the engineers. Remote employees make sense. But moving a department or writing group to Seattle makes no sense.
You can trace the fall of apple’s docs directly to how far from infinite loop and Apple Park the department is.
Why is Apple writing docs in Seattle?
Devpubs (as a department) should be in Apple Park, with the engineers. Remote employees make sense. But moving a department or writing group to Seattle makes no sense.
I’ve seen the exact opposite take as well.
There’s a case to be made that if you’re writing the docs like you would do black box testing, you
do a better job explaining stuff that is obvious to Apple’s own developers, but not so much to third parties,
might discover issues that don’t affect Apple’s own developers at all (reliance on internal tooling) or less
Plus, Apple’s engineering org appears to have a scaling problem and they’re very Silicon Valley-focused (albeit not -exclusive), and docs could be an area where they could relieve some pressure by going with separate teams. Keep in mind, too, that Apple Park “only” hosts 12,000 employees.
(Your take is valid as well. But I think it’s interesting that criticisms come from both sides.)
