The State of Apple’s Developer Documentation

(Ahem, clears throat...) Apple are a services company now. What would they need to supply documentation for?

Meanwhile, Microsoft’s docs also went through a migration, but in their case, the end result was making them open-source on GitHub, accepting pull requests for improvements.

It seems to me like there's a (planned? in-progress?) reset going on, and they decided the best thing to do was mass deprecated all the existing docs to start fresh. I understand the appeal of that, but it really doesn't make sense to do that without clear communication about what's going on. How many of these docs are going to be replaced by great new things? (I'm very pessimistic that AppKit docs will get much love.) Will they at least make it so we can effectively search for old docs? Even operating under the assumption that this is part of a planned big push to improve docs, they're handling things pretty poorly.

"It seems to me like there's a (planned? in-progress?) reset going on"

Perhaps, but why start deprecating and archiving long before the new stuff is ready to go live?

I'm inclined to expect the worst so I suspect there *is* a reset coming up but it'll be something terrible.

I’m actually afraid Apple’s management believes that WWDC videos *are* the ultimate documentation.

I agree with Jon H, if they simply were in the process of rewriting some docs, they would publish new docs before deprecating old ones.

"It seems to me like there's a (planned? in-progress?) reset going on"

Maybe they replace their storage by SSD, because the reboot is very slow…

Apparently, Tim Cook's next motto is: "Everyone can code without a documentation".

developer.apple.com doesn't seem to block indexing of /library/archive. Here's the contents of robots.txt:

# robots.txt for http://developer.apple.com/
User-agent: *
Disallow: /click/
Disallow: /cgi-bin/
Disallow: /survey/
Disallow: /temp/
Disallow: /search/
Disallow: /legacy/library/
Disallow: /unsubscribe/
Disallow: /reference/

Search engines seem to index it just fine: https://duckduckgo.com/?q=site%3Adeveloper.apple.com%2Flibrary%2Farchive

"It seems to me..."

When it comes to platform documentation, the words "It seems to me" never should apply; the only appropriate words are "It is" or "It isn't."

Here is what you see today if you're new to CloudKit and want to get started with it: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitQuickStart/Introduction/Introduction.html

@Jordan Morgan

https://developer.apple.com/documentation/cloudkit

Isn't that a maintained version of the CloudKit docs? Or is it missing content from the archive?

@Ben Like most of the new docs, it’s just reference—missing the conceptual stuff.

[…] Michael Tsai – Blog – The State of Apple’s Developer Documentation – […]

Apple has thankfully addressed the search issues mentioned in my tweet from last year - they removed the robots.txt and meta tag exclusions for the archive content, and are including results from it in their own search engine now as well.

By vocation I code for Windows, and their docs are tepid quality but usable. By avocation I code for iOS. As an occasional-time iOS devo I have struggled to understand how to use the "kits". The introduction pages have always been on the opaque side, but at least we had them. Examples are separated from the docs, and usually out of date. Thanks to all the legions of folks blogging how-tos, making up for Apple's abysmal docs (and don't get me started on how insubstantial the WWDC videos are learning from scratch -- looking at you, chain of "what's new in ___" videos.)

[…] The State of Apple’s Developer Documentation […]

[…] a blog post on Monday, macOS developer Michael Tsai makes note of a handful of fellow coders expressing […]

I have 20+ years as a technical writer having written API and SDK documentation for C, C++, and RESTful API documentation. Remotely, I could write this, does anyone know how I can apply to Apple?

Apple used to have pretty much the best documentation out there. Their old Addison-Wesley series of books, including "Inside Macintosh", were practically the stuff of legend. Sure, there were flaws here and there, and some of the content was better than others, but that's normal. On average, though, their stuff was great. Especially when coupled with the tech notes and such put out by the DTS team.

Apple's docs turned downhill fast when they switched to automatically generating docs instead of using human-written, structured, and curated materials.

Seeing the state of things today, and how hard it is to find accurate information (if any exists *at all*), is depressing and a genuine cause for serious frustration.

Andrew Madsen: “It seems to me like there's a (planned? in-progress?) reset going on, and they decided the best thing to do was mass deprecated all the existing docs to start fresh.”

I think it’s simpler than that. They replaced their old CMS a few years back and didn’t have the resources and/or motivation to migrate all the existing material. As others have noted, software documentation is all too often viewed as a resource sink, consuming money without generating it. That the whole house of cards will eventually fall down without it isn’t really going to register with the sort of New Coke leadership now running Apple. Without strong leadership aiming the entire organization at solid deliverable goals (creating and owning new customer markets) and kicking asses to get that delivered, it’s reverting to the disunited mess of private fiefdoms all doing whatever suits themselves.

Thus the Swifties create a rolling car-crash for their own entertainment and the doc team refuses to constantly clean up after them. All the customer (App developers) needed was a better language for Cocoa development, so they flush much of the accumulated value of that 30-year investment instead. Individual careers and reputations will be made, power bases erected and bonuses pocketed, but who’s looking out for what’s in the company’s best interests? Like any organization Apple needs steering, but nobody’s holding the wheel. And so it goes.

Eric Shepherd: “Apple's docs turned downhill fast when they switched to automatically generating docs instead of using human-written, structured, and curated materials.”

Automatically-generated is still human-written; it’s just faster and more accurate to machine-collate. If anything, it should make a better-quality product, not least because it can be instantly automatically delivered through interactive context-aware tooling. If the output is bad, it’s because the input is bad.

Which brings us back to PEBKAC, and the eternal problem of who’s going to do the job that nobody likes doing and nobody wants to pay for either.

Will Notbepublished: “Apparently, Tim Cook's next motto is: "Everyone can code without a documentation".”

That would be the ideal endpoint, but it requires a unification of language, tooling, and documentation, combined with a rigorous intolerance for anything that does not lend itself to clear explanation. Systems like Lisp Machines and Logo are outliers. I don’t the mainstream’s ever even tried it, not only because it’s much harder to do but because there just isn’t much personal glory to be had by delivering something so easy and seamless to use that no-one even notices it’s there.

" If anything, it should make a better-quality product"

Nonsense. At best it provides pretty-printed code comments formatted to pretend to be documentation.

But that doesn't do anything to provide higher level conceptual documentation about how things are meant to be used or how they work together. That kind of material would be out of place as code comments, so doesn't appear in the machine-generated documentation.

@Jon: “That kind of material would be out of place as code comments”

Why? Why should code and documentation be treated as if they’re unrelated? If the language and its tools don’t treat documentation as first-class program structures, fix the language and its tools.

https://en.wikipedia.org/wiki/Literate_programming

Oh, and if programmers complain, replace them. Because any programmer who can’t explain how to use their software isn’t qualified to write software for others to use.

"Why should code and documentation be treated as if they’re unrelated?"

If you're talking about how five classes work together which class do you put the documentation in? Do you repeat the text in all five classes?

@Jon H: Perhaps, instead of putting your documentation in your classes, you should try putting your classes in your documentation?

[…] to adopt this service by June 30th, it seems reasonable to expect decent documentation. Sadly, like most of Apple’s recent developer documentation, it’s sorely lacking. For example, Apple vaguely states that you can implement Sign in with Apple […]