{"id":32413,"date":"2021-05-07T16:27:50","date_gmt":"2021-05-07T20:27:50","guid":{"rendered":"https:\/\/mjtsai.com\/blog\/?p=32413"},"modified":"2021-05-10T15:41:36","modified_gmt":"2021-05-10T19:41:36","slug":"reimagining-apples-documentation","status":"publish","type":"post","link":"https:\/\/mjtsai.com\/blog\/2021\/05\/07\/reimagining-apples-documentation\/","title":{"rendered":"Reimagining Apple&rsquo;s Documentation"},"content":{"rendered":"<p><a href=\"https:\/\/www.hackingwithswift.com\/articles\/231\/reimagining-apples-documentation\">Paul Hudson<\/a>:<\/p>\n<blockquote cite=\"https:\/\/www.hackingwithswift.com\/articles\/231\/reimagining-apples-documentation\">\n<p>For a number of years my #1 WWDC wish was that Apple would do something to dramatically rethink its approach to developer documentation.<\/p>\n<p>[&#8230;]<\/p>\n<p>The top 500 most popular APIs (measured by page views) should have example code attached, ideally several examples with headers clearly marking what problem is being solved.<\/p>\n<p>[&#8230;]<\/p>\n<p>Any place where header files have documentation comments and their matching online documentation is &ldquo;No overview available&rdquo; should have the header docs copied straight online.<\/p>\n<p>No APIs mentioned in the WWDC Platforms State of the Union talk should be allowed to ship with &ldquo;No Overview Available&rdquo; as their documentation &#x2013; either can the feature or prioritize documentation.<\/p>\n<p>Link directly to relevant WWDC videos from API pages, ideally to precise timestamps. Even better, make sure everything mentioned in those videos gets included in the text documentation too.<\/p>\n<\/blockquote>\n\n<p>Previously:<\/p>\n<ul>\n<li><a href=\"https:\/\/mjtsai.com\/blog\/2021\/02\/26\/apple-documentation-and-swiftui-for-mac\/\">Apple Documentation and SwiftUI for Mac<\/a><\/li>\n<li><a href=\"https:\/\/mjtsai.com\/blog\/2020\/11\/10\/on-apples-piss-poor-documentation\/\">On Apple&rsquo;s Piss-Poor Documentation<\/a><\/li>\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=\"reimagining-apples-documentation-update-2021-05-10\">Update (2021-05-10): <a href=\"https:\/\/twitter.com\/KenHatesSoftwar\/status\/1390793402292183041\">Ken Harris<\/a>:<\/p>\n<blockquote cite=\"https:\/\/twitter.com\/KenHatesSoftwar\/status\/1390793402292183041\">\n<p>You forgot:<\/p>\n<p>&#8226; Stop moving webpages around all the time without adding HTTP redirects.<\/p>\n<p>&#8226; The Human Interface Guidelines shouldn&rsquo;t link to a guide on developer.apple.com that tells us to use a feature of Xcode that was removed 5 years ago.<\/p>\n<\/blockquote>","protected":false},"excerpt":{"rendered":"<p>Paul Hudson: For a number of years my #1 WWDC wish was that Apple would do something to dramatically rethink its approach to developer documentation. [&#8230;] The top 500 most popular APIs (measured by page views) should have example code attached, ideally several examples with headers clearly marking what problem is being solved. [&#8230;] Any [&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":"2021-05-07T20:27:54Z","apple_news_api_id":"2d92ca31-c00a-4eec-96b1-28b5a7fdc261","apple_news_api_modified_at":"2021-05-10T19:41:40Z","apple_news_api_revision":"AAAAAAAAAAAAAAAAAAAAAA==","apple_news_api_share_url":"https:\/\/apple.news\/ALZLKMcAKTuyWsSi1p_3CYQ","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,31,1837,30,1891,71,1221],"class_list":["post-32413","post","type-post","status-publish","format-standard","hentry","category-programming-category","tag-documentation","tag-ios","tag-ios-14","tag-mac","tag-macos-11-0","tag-programming","tag-wwdc"],"apple_news_notices":[],"_links":{"self":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/32413","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=32413"}],"version-history":[{"count":2,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/32413\/revisions"}],"predecessor-version":[{"id":32435,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/32413\/revisions\/32435"}],"wp:attachment":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/media?parent=32413"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/categories?post=32413"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/tags?post=32413"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}