A couple years ago, maybe around Swift's debut, Apple began to mark all their sample code, projects, programming guides, technical notes, etc, as deprecated and unmaintained with a header on each page stating so, and putting it all in their "Documentation Archive" [0]
They've had a new push to make sure that the remaining official documentation is available in either Swift or Objective-C, but I have yet to see any attempt at migrating some of their best documentation: CoreBluetooth Programming Guide, CoreImage Programming Guide, or CoreData Programming Guide [1]. These are hugely helpful documents that take a much higher level approach than just API documentation and get to the heart of the design of a framework, with helpful diagrams, etc.
I understand that Apple has a huge body of work regarding documentation, and that it would be unfair for us to require them to never deprecate any of their documentation, but at this point, we basically have header files, documents automatically generated by header files, with several large swatch of that even being undocumented [2].
I do think that Apple made a huge effort with SwiftUI to provide meaningful, helpful documentation at the time of the announcement [3], and I don't want that to get lost in the discussion. Unfortunately the framework has iterated so quickly that much of it is out of date.
However, when Xamarin [4] independently documents some of Apple's APIs better than Apple does... it is indeed time for a call to action.
This is especially sad because Apple used to have some of the best documentation ever available. I basically learned how to program through using their documentation.
All this, yes. And the ongoing use of "shadow documentation" where important details are mentioned halfway through a WWDC presentation but not written down anywhere is a hair puller too. Especially when they start taking down videos covering APIs that are still in active use!! (WWDC videos apparently have a 5-year lifespan at the moment. While 5 years is a long time and a lot can change in that period, not everything changes.)
Along with this, they removed or not generated PDFs like they once had. This is really painful for folks that have problems with looking at a screen for an extended period. They don't even have downloadable documentation that can be read on an iPad. The lack of PDF is a real issue for me.
The continued failing of example code is really painful.
Serious question (I asked because my spouse is starting to have some of these issues) - if you can read a PDF on the iPad, how is that different from reading the HTML docs on the iPad? Is it something with the layout, or is it the cognitive load of having to click a lot of links rather than having a linear layout of the text? I'm interested in learning more about this to help my spouse out!
I get the feeling Adobe spends a lot of time making PDF work very well for reading. Different kerning maybe?
I have the problem that even an iPad is a tiring for reading even with the ability to position it in a more comfortable reading position than a monitor. I need to print stuff out and html truly sucks for printing. I can use e-ink and that seems fine which isn't an option either. Bandwidth is still not universal or cheap.
They've had a new push to make sure that the remaining official documentation is available in either Swift or Objective-C, but I have yet to see any attempt at migrating some of their best documentation: CoreBluetooth Programming Guide, CoreImage Programming Guide, or CoreData Programming Guide [1]. These are hugely helpful documents that take a much higher level approach than just API documentation and get to the heart of the design of a framework, with helpful diagrams, etc.
I understand that Apple has a huge body of work regarding documentation, and that it would be unfair for us to require them to never deprecate any of their documentation, but at this point, we basically have header files, documents automatically generated by header files, with several large swatch of that even being undocumented [2].
I do think that Apple made a huge effort with SwiftUI to provide meaningful, helpful documentation at the time of the announcement [3], and I don't want that to get lost in the discussion. Unfortunately the framework has iterated so quickly that much of it is out of date.
However, when Xamarin [4] independently documents some of Apple's APIs better than Apple does... it is indeed time for a call to action.
This is especially sad because Apple used to have some of the best documentation ever available. I basically learned how to program through using their documentation.
[0] - https://developer.apple.com/library/archive/navigation/
[1] - https://developer.apple.com/library/archive/documentation/Co...
[2] - https://nooverviewavailable.com
[3] - https://developer.apple.com/documentation/swiftui
[4] - https://twitter.com/akashivskyy/status/1187790245804367873