Monday, May 20, 2019

The State of Apple’s Developer Documentation

Scott Anguish:

It appears that most of the old iOS conceptual documents have been moved to the documentation archive and are now unsupported.

Is there really no iOS Text Programming concepts? Or are the indexes just that bad?

That is more than a decade of work by dozens, just being abandoned.

I can’t even grasp how that’s any solution.

If this is the case every single iOS developer should be screaming from the rafters. It’s by far the stupidest move I’ve seen in a decade.

You can’t write apps without authoritative docs.

It’s bad enough the reference doc has reached the point it has.

It’s surprising how much of the documentation is marked as legacy, archived, not up-to-date, or was never written in the first place. At first I thought this was because of some sort of internal transition, but it’s been going on for years now and does not seem to be getting any better.

Steve Tibbett:

As far as I can tell, this is the only documentation on IAP receipt validation. This is part of a current system that’s making Apple billions of dollars. There are errors in it, and it’s “no longer being updated”.

Martin Pilkington:

Fun fact: when I was looking up docs for Help Books for my Appreciating AppKit post, one of the few Mac features already supported in Marzipan, it took ages to find as they’re only available in the documentation archive

Matt Stevens:

If you’re struggling to find an Apple developer document you know exists, it’s not just you. http://developer.apple.com’s robots.txt disallows /library/archive/, where all of the old docs now live. Apple’s own “Search Documentation Archive”…doesn’t search the archive.

Previously:

Update (2019-05-21): Adam Maxwell:

I remember the good old days when people were annoyed that you couldn’t figure out Cocoa bindings without the stuff mmalc posted on his personal website. That was nothing compared to when the doc browser turned into a lousy webpage instead of Cocoa views and Search Kit.

Randy Scovil:

I’m wondering how much has really disappeared. I used to point students there all the time for source code examples and now I find most any search for those comes up empty. Que?

Jonathan Fischer:

For what it’s worth, DuckDuckGo seems to be ignoring that robots.txt entry for /library/archive. I usually find what I’m looking for without much trouble:

Francisco Tolmasky:

Died Apple just not document AppKit anymore? I can’t find anything about NSWindowTab. Is all information just in like WWDC videos?

See also: Hacker News.

X0R:

Sad but true. 10 years ago when I were starting to learn iOS development it was one of the best documentations I’ve ever worked with. And now it’s more like Microsoft’s in it’s dark age.

Update (2019-05-22): macshome:

One of my biggest issues with the new docs page is discoverability. And yes, I’ve filed radars on it.

Kyle Howells:

This is now my number one WWDC wishlist item.

Anything else is a bonus, but Apple’s documentation has fallen so far the knowledge about how the platform works is now being buried in archived documents, old WWDC videos and release notes.

Update (2019-05-28): Kyle Howells:

Apple’s developer documentation doesn’t show what class the method I’m looking at is for anywhere on the page.

Update (2019-05-30): Scott Anguish:

From comments on your post today “Apple’s docs turned downhill fast when they switched to automatically generating docs instead of using human-written, structured, and curated materials.”

Except that’s not what happened. It’s all human-written, structured, and curated.

27 Comments RSS · Twitter

(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.

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 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.

Jean-Daniel

"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…

Will Notbepublished

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."

@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 – […]

Matt Stevens

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.

Bob Peterson

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 […]

Russ Urquhart

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 […]

Leave a Comment