State of Documentation is Ambiguous and Difficult to Use

Originator:jordan
Number:rdar://46523695 Date Originated:12/06/2018
Status:Open Resolved:
Product:Documentation Product Version:
Classification:Suggestion Reproducible:
 
The documentation archive's usefulness creates a stark juxtaposition to the confusing state of the "new" documentation. Several links take you to the documentation archive, which link back to the new documentation creating some sort of "circular reference" between them.

We all want this platform to succeed, and as a veteran of the iOS platform even I find the process of locating what I need to be difficult, frustrating and more than anything a time sink. I fear for what new developers might face when trying to get started in this industry. It's my believe that Apple is far behind in providing easy access to code samples and other helpful guidelines (for example, a simple Hello World app). Some of these things exist, but where? And how do I find them?

Example: CloudKit
If I want to start working with CloudKit, I visit the documentation found here: https://developer.apple.com/documentation/cloudkit?language=objc

After reading the overview, I'm linked to this quick start guide. The first thing I see as a developer is that it's deprecated:
https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitQuickStart/Introduction/Introduction.html

And it links back to the original site. This is counter intuitive. 

Further, it's extremely hard (or not possible at all) any longer to:
1) Easily find code samples
2) View technical notes
3) Find release notes for what's new in iOS
4) etc...

The documentation archive was not pretty, but what it was *is* the most important thing with documentation - easy to use. My suggestion is to make the things we need as developers easy to find again, however Apple sees fit. We need to find code samples, we need easy access to technical notes and we need those things not to be scattered across the "new" documentation while also being buried away in the documentation archive which we apparently aren't even supposed to visit. I know this is a non trivial problem to solve at Apple's scale, but I do believe it's an important one.

Thanks for your time.

Comments


Please note: Reports posted here will not necessarily be seen by Apple. All problems should be submitted at bugreport.apple.com before they are posted here. Please only post information for Radars that you have filed yourself, and please do not include Apple confidential information in your posts. Thank you!