{"id":26972,"date":"2019-10-18T16:16:19","date_gmt":"2019-10-18T20:16:19","guid":{"rendered":"https:\/\/mjtsai.com\/blog\/?p=26972"},"modified":"2019-11-01T11:24:21","modified_gmt":"2019-11-01T15:24:21","slug":"no-overview-available","status":"publish","type":"post","link":"https:\/\/mjtsai.com\/blog\/2019\/10\/18\/no-overview-available\/","title":{"rendered":"No Overview Available"},"content":{"rendered":"<p><a href=\"https:\/\/twitter.com\/mattt\/status\/1185234430425628672\">Mattt Thompson<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/mattt\/status\/1185234430425628672\"><p>It&rsquo;s become a truism among iOS and macOS developers that Apple&rsquo;s documentation is often incomplete or missing altogether.<\/p>\n<p>But to what extent is this actually the case? With a bit of web scraping, I was able to come up with some numbers:<\/p>\n<p><a href=\"https:\/\/nooverviewavailable.com\">nooverviewavailable.com<\/a><\/p><\/blockquote>\n\n<p>It&rsquo;s the new &ldquo;Description forthcoming.&rdquo;<\/p>\n\n<p>You have to look beyond the colors, and even the numbers. For example, <a href=\"https:\/\/nooverviewavailable.com\/healthkit\/\">HealthKit<\/a> gets 100% for documenting 7\/7 symbols. But if you <a href=\"https:\/\/developer.apple.com\/documentation\/healthkit\">click through<\/a> 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 <a href=\"https:\/\/twitter.com\/mattt\/status\/1185259094665388033\">admitted<\/a> to be undocumented, rather than the actual number of symbols.<\/p>\n\n<p>But that doesn&rsquo;t mean there&rsquo;s no documentation for them. Many of the symbols have good doc comments in the headers. Yet despite Apple releasing <a href=\"https:\/\/en.wikipedia.org\/wiki\/HeaderDoc\">HeaderDoc<\/a> 19 years ago, it doesn&rsquo;t seem to have an automated way to get those comments into the published documentation.<\/p>\n\n<p>Previously:<\/p>\n<ul>\n<li><a href=\"https:\/\/mjtsai.com\/blog\/2019\/05\/20\/the-state-of-apples-developer-documentation\/\">The State of Apple&rsquo;s Developer Documentation<\/a><\/li>\n<\/ul>\n\n<p id=\"no-overview-available-update-2019-10-21\">Update (2019-10-21): <a href=\"https:\/\/twitter.com\/mattt\/status\/1185563855251894273\">Mattt Thompson<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/mattt\/status\/1185563855251894273\">\n<p>Source code for NoOverviewAvailable.com is now available <a href=\"https:\/\/github.com\/NSHipster\/NoOverviewAvailable.com\">on GitHub<\/a>[&#8230;]<\/p>\n<\/blockquote>\n\n<p id=\"no-overview-available-update-2019-10-25\">Update (2019-10-25): <a href=\"http:\/\/mikezornek.com\/posts\/2019\/10\/full-time-spaceship-employees-only\/\">Mike Zornek<\/a>:<\/p>\n<blockquote cite=\"http:\/\/mikezornek.com\/posts\/2019\/10\/full-time-spaceship-employees-only\/\">\n<p>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.<\/p>\n<p>This is mostly true, but a major factor that is not brought up is Apple&rsquo;s reluctance to hire <strong>remote<\/strong> documentation writers.<\/p>\n<p>[&#8230;]<\/p>\n<p>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 (<a href=\"https:\/\/www.glassdoor.com\/Salary\/Apple-Senior-Technical-Writer-Salaries-E1138_D_KO6,29.htm\">Glassdoor listing<\/a>) than a developer and yet the cost of living out there is crazy for both professions.<\/p>\n<\/blockquote>\n<p>See also: <a href=\"https:\/\/atp.fm\/episodes\/349\">Accidental Tech Podcast<\/a>.<\/p>\n\n<p id=\"no-overview-available-update-2019-11-01\">Update (2019-11-01): <a href=\"https:\/\/v4.chriskrycho.com\/2019\/apple-your-developer-documentation-is-garbage.html\">Chris Krycho<\/a> (via <a href=\"https:\/\/news.ycombinator.com\/item?id=21376744\">Hacker News<\/a>, <a href=\"https:\/\/apple.slashdot.org\/story\/19\/10\/28\/173216\/apple-your-developer-documentation-is-garbage\">Slashdot<\/a>):<\/p>\n<blockquote cite=\"https:\/\/v4.chriskrycho.com\/2019\/apple-your-developer-documentation-is-garbage.html\">\n<p>The number of parts of this ecosystem which are entirely undocumented is frankly shocking to me.<\/p>\n<p>[&#8230;]<\/p>\n<p>The current state of Apple&rsquo;s software documentation is the worst I&rsquo;ve ever seen for any framework anywhere.<\/p>\n<p>[&#8230;]<\/p>\n<p>Given what I know of Apple&rsquo;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 <em>are<\/em> responsible for writing docs). But that does not make it any less a failure of Apple&rsquo;s engineering <em>organization<\/em>. The job of an <abbr>API<\/abbr> engineering organization is to support those who will consume that <abbr>API<\/abbr>. I don&rsquo;t doubt that many of Apples <abbr>API<\/abbr> engineers would <em>love<\/em> 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&rsquo;m wrong, if I <em>should<\/em> doubt that, because Apple&rsquo;s engineering culture <em>doesn&rsquo;t<\/em> value this, then that&rsquo;s even worse an indictment of the engineering culture.) This kind of thing has to change at the level of the entire engineering organization.<\/p>\n<\/blockquote>\n\n<p><a href=\"https:\/\/twitter.com\/DamienPetrilli\/status\/1188890479129182208\">Damien Petrilli<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/DamienPetrilli\/status\/1188890479129182208\">\n<p>Apple not documenting and providing unstable tools will push people to use cross platform and hybrid technology.<\/p>\n<p>Why use native when the other tools are taking the heat for you and provide documentation?<\/p>\n<\/blockquote>\n\n<p>I&rsquo;ve even seen people pointing to documentation for Microsoft&rsquo;s cross-platform stuff as being the authoritative source on how macOS works, because Apple&rsquo;s own documentation on the topic is absent.<\/p>\n\n<p><a href=\"https:\/\/news.ycombinator.com\/item?id=21377358\">ChrisMarshallNY<\/a>:<\/p>\n<blockquote cite=\"https:\/\/news.ycombinator.com\/item?id=21377358\">\n<p>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&rsquo;s open codebases. Their code is exceptionally well-documented.<\/p>\n<p>[&#8230;]<\/p>\n<p>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.<\/p>\n<p>This was clearly not something the tester liked.<\/p>\n<\/blockquote>\n\n<p><a href=\"https:\/\/twitter.com\/stroughtonsmith\/status\/1188822137282412545\">Steve Troughton-Smith<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/stroughtonsmith\/status\/1188822137282412545\">\n<p>When I was learning Cocoa, Apple&rsquo;s docs were the best around. These days, it&rsquo;s all left to rot in the Documentation Archive, and it&rsquo;s much harder to find anything helpful for newer APIs. If this year&rsquo;s meme helps Apple realize the damage they&rsquo;ve done to their documentation, great<\/p>\n<p>What happened to Apple&rsquo;s docs? I think the biggest reason is Swift: Apple&rsquo;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.<\/p>\n<\/blockquote>\n\n<p><a href=\"https:\/\/twitter.com\/dimitribouniol\/status\/1182716092415758343\">Dimitri Bouniol<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/dimitribouniol\/status\/1182716092415758343\">\n<p>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.<\/p>\n<p>Now, there are a ton of &ldquo;beginner&rdquo; resources, but almost no guidance on the more obscure APIs and frameworks<\/p>\n<p>I feel like they could easily hire remote developers to document <em>existing<\/em> APIs without feature of leaks, just to flesh out undocumented things, and any new APIs right after WWDC starts and during the beta period.<\/p>\n<\/blockquote>\n\n<p><a href=\"https:\/\/twitter.com\/brentsimmons\/status\/1189635722594136067\">Brent Simmons<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/brentsimmons\/status\/1189635722594136067\">\n<p>There has been some discussion about Apple&rsquo;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.<\/p>\n<p>But note: Apple is actually hiring in Seattle.<\/p>\n<\/blockquote>\n\n<p><a href=\"https:\/\/twitter.com\/FlexMonkey\/status\/1189215179654991872\">FlexMonkey<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/FlexMonkey\/status\/1189215179654991872\">\n<p>Whoa! The Accelerate page has been updated: every article and piece of sample code is available in one place.<\/p>\n<\/blockquote>\n\n<p><a href=\"https:\/\/twitter.com\/rustyshelf\/status\/1190043907326799872\">Russell Ivanovic<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/rustyshelf\/status\/1190043907326799872\">\n<p>Forget &ldquo;No overview available&rdquo; Apple&rsquo;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&rsquo;t recognise it<\/p>\n<\/blockquote>","protected":false},"excerpt":{"rendered":"<p>Mattt Thompson: It&rsquo;s become a truism among iOS and macOS developers that Apple&rsquo;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: nooverviewavailable.com It&rsquo;s the new &ldquo;Description forthcoming.&rdquo; You have to look beyond [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"apple_news_api_created_at":"2019-10-18T20:16:22Z","apple_news_api_id":"3d18985a-d414-44b3-95c8-3dfb525b4592","apple_news_api_modified_at":"2019-11-01T15:24:27Z","apple_news_api_revision":"AAAAAAAAAAAAAAAAAAAAAw==","apple_news_api_share_url":"https:\/\/apple.news\/APRiYWtQURLOVyD37UltFkg","apple_news_coverimage":0,"apple_news_coverimage_caption":"","apple_news_is_hidden":false,"apple_news_is_paid":false,"apple_news_is_preview":false,"apple_news_is_sponsored":false,"apple_news_maturity_rating":"","apple_news_metadata":"\"\"","apple_news_pullquote":"","apple_news_pullquote_position":"","apple_news_slug":"","apple_news_sections":"\"\"","apple_news_suppress_video_url":false,"apple_news_use_image_component":false,"footnotes":""},"categories":[4],"tags":[164,634,937,31,1667,30,1666,74,71,251],"class_list":["post-26972","post","type-post","status-publish","format-standard","hentry","category-programming-category","tag-documentation","tag-headerdoc","tag-hiring","tag-ios","tag-ios-13","tag-mac","tag-macos-10-15","tag-opensource","tag-programming","tag-working"],"apple_news_notices":[],"_links":{"self":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/26972","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/comments?post=26972"}],"version-history":[{"count":4,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/26972\/revisions"}],"predecessor-version":[{"id":27122,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/26972\/revisions\/27122"}],"wp:attachment":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/media?parent=26972"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/categories?post=26972"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/tags?post=26972"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}