Reimagining Apple’s Documentation
For a number of years my #1 WWDC wish was that Apple would do something to dramatically rethink its approach to developer documentation.
[…]
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.
[…]
Any place where header files have documentation comments and their matching online documentation is “No overview available” should have the header docs copied straight online.
No APIs mentioned in the WWDC Platforms State of the Union talk should be allowed to ship with “No Overview Available” as their documentation – either can the feature or prioritize documentation.
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.
Previously:
- Apple Documentation and SwiftUI for Mac
- On Apple’s Piss-Poor Documentation
- The State of Apple’s Developer Documentation
Update (2021-05-10): Ken Harris:
You forgot:
• Stop moving webpages around all the time without adding HTTP redirects.
• The Human Interface Guidelines shouldn’t link to a guide on developer.apple.com that tells us to use a feature of Xcode that was removed 5 years ago.
1 Comment RSS · Twitter
"The top 500 most popular APIs (measured by page views) should have example code attached"
Those are probably well served by non-Apple code that's available. IMHO the the less popular ones that nobody knows how to use need example code as well, because you can't find that on StackOverflow.
