
Apple Developer Documentation Is Missing - chriskrycho
https://v4.chriskrycho.com/2019/apple-your-developer-documentation-is-garbage.html
======
Shank
Maybe I'm the only one, but when I start looking into a project, I start at
the API docs and work from there. I really need to know if key features I want
are viable on the platform or not. If I want to use an accessibility API to,
in a supported way, read all of the items in every menu in the menu bar, how
do I do that? Is it supported? Is there a set of best practices I should
follow?

The problem with not documenting things is that developers like me are turned
off before we start. I don't want to bend the platform so far that it breaks.
I want the limits. I'm tired of reading stories about apps being pulled for
using private APIs, or breaking in future versions because they're removed. I
want to do things in a supported way so I can make everyone happy.

Right now, I can't even see the boundaries of what's possible, because nothing
is documented. I don't even want to try to write for Apple platforms, because
it's entirely inscrutable and unpredictable.

~~~
bob1029
You are not the only one.

My most recent experience with Apple's documentation (regarding some iOS 13
API concern), left me with a sense of impending doom and hopelessness. After
about 5 minutes I gave up and went back to playing the google/stackoverflow
search game.

I have become very addicted to the quality of Microsoft's documentation for
things like .Net Core & C#, and have found it virtually impossible to tolerate
reading documentation from any other vendor at this point. A completely
arbitrary but hopefully obvious side-by-side comparison:

Exhibit A:

[https://docs.microsoft.com/en-
us/dotnet/api/system.linq.enum...](https://docs.microsoft.com/en-
us/dotnet/api/system.linq.enumerable.distinct?view=netcore-3.0)

Exhibit B:

[https://developer.apple.com/documentation/coreimage/cicolor/...](https://developer.apple.com/documentation/coreimage/cicolor/1438084-init)

~~~
Vomzor
A better example would be:

\- Apple:
[https://developer.apple.com/documentation/coreimage/cicolorc...](https://developer.apple.com/documentation/coreimage/cicolorcubewithcolorspace?language=occ)

\- Microsoft: [https://docs.microsoft.com/en-
us/dotnet/api/coreimage.cicolo...](https://docs.microsoft.com/en-
us/dotnet/api/coreimage.cicolorcubewithcolorspace?view=xamarin-ios-sdk-12)

~~~
kalleboo
Oh god that's both hilarious and sad at the same time. Maybe Apple should
contract Microsoft to write their own documentation for them?

~~~
valleyer
Sadly, Apple actually does have good documentation for Core Image. It just
never made it into their new system and is instead languishing in the
"archive":

[https://developer.apple.com/library/archive/documentation/Gr...](https://developer.apple.com/library/archive/documentation/GraphicsImaging/Reference/CoreImageFilterReference/index.html#//apple_ref/doc/filter/ci/CIColorCubeWithColorSpace)

Apple deployed a new documentation system, and no one stopped to make sure all
the "old" stuff got translated through.

------
chooseaname
> Apple, if you want developers to love your platform — and you should,
> because good developers are your lifeblood — and if you don’t want them to
> flee for other platforms — and you should be worried about that, because the
> web is everywhere and Microsoft is coming for you — then you need to take
> this seriously. Adopt the mentality that has served other frameworks and
> languages so well: If it isn’t documented, it isn’t done.

Apple has enough rabid supporters, they can lose the occasional developer to
bad docs. Apple doesn't care or need to care. They are arrogant that way.
Also, what other platforms? Android? A fair portion of iOS devs are _also_
already Android devs.

Look, this is just going to fall on deaf ears. Apple isn't listening. Their
machine is output only.

~~~
sillysaurusx
_Look, this is just going to fall on deaf ears. Apple isn 't listening. Their
machine is output only._

That's not really true. Apple is active on Twitter and actively reaches out to
correct problems.

For example, when I complained that their Xcode beta hangs when you open a
large file, an Xcode dev reached out to me and asked for a repro case.
[https://twitter.com/theshawwn/status/1175197286349119490](https://twitter.com/theshawwn/status/1175197286349119490)

(I'm not an Apple fanboy, just a dev.)

~~~
AlexandrB
Isn't that the exception that proves the rule though? Why is Twitter the most
effective way to get developer support from Apple as opposed to their own
website?

~~~
52-6F-62
Yeah. As much as I appreciate their responsiveness on Twitter, it doesn't much
help those of us who are _not_ on Twitter.

(Tangential rant: I dislike how it seems like the most effective path for
anything resembling customer service from _many_ companies is to call them out
on Twitter alone. I've written emails to some companies over _months_ to no
single response—but to look on their Twitter you'll see an answer within
hours, or minutes.)

~~~
dnautics
That shouldn't be surprising as Twitter is a public forum, so there's more
accountability.

~~~
52-6F-62
I'm not surprised. I'm a bit miffed, though. We shouldn't have to shame
companies to get a bit of customer service—let alone a response to an email.

------
travisgriggs
I work half and half pretty much maintaining the same app in both iOS and
Android. Since the introduction of Swift, the Apple docs have become much
terser (it's like Jony Ives slimness fettish got a hold of them). Even with
that, they're better (by far) than what I find with the Android docs. The
Android docs "explain" very little.

~~~
iainmerrick
Android suffers a lot from quantity over quality. Classes are usually
documented, but usually for a function like “setReturnVectorFlag” it’s just
_sets the return vector flag_.

 _Edit to add:_ I also work on both platforms, and I’d say iOS (along with
MacOS) is usually easier to work with because the design tends to be sane and
the names are fairly descriptive; whereas Android has a lot of weird and
questionable design decisions so it’s harder to guess how things really work.
On the upside for Android, it’s often possible to just read the source code
(at least for the core OS).

I think the docs are about equally bad overall.

~~~
andybak
> usually for a function like “setReturnVectorFlag” it’s just sets the return
> vector flag.

Ah - the "repeat the method names with spaces in it" style of documentation.

This is merely an exaggerated form of a trap that the majority of
documentation falls into to some degree - documenting the "what" but
neglecting the "why" or "how".

It tells you the bit you can easily work out by intuition, reading the source
or using your IDE's features.

And it leaves out the really important parts: "how should I use this method?"
and "why would I need to?"

Method based documentation also has problems explaining how API calls are used
in concert. Understanding each method in isolation something leaves huge gaps
in understanding how they are to be used together.

And no - you can't plug the gaps with lazy video tutorials.

~~~
oefrha
> Ah - the "repeat the method names with spaces in it" style of documentation.

That's usually a symptom of aggressive linters enforcing the rule that every
single public method must be documented. Programmers then produce useless
"documentation" to shut the linters up. Utter waste of disk space.

~~~
kbenson
I can see that as possible, and I can also see how it might very negatively
impact a documentation drive on accident. One of those things that sounds
good, and could be beneficial, but when enacted without strong guidance just
ends up combining with culture or human nature to make things worse. E.g. a
rule that says there must be documentation, but without standards and enough
review to make sure that it's good documentation. Stats show things getting
better, but that's because we always drift towards optimizing what we measure,
which is not always the same what we actually want.

------
mmusson
When I first learned iOS ten years ago I thought the documentation was
outstanding. It had good API level documentation as well as a large number of
guides that showed the right way to use the API to implement particular
features.

I recently returned to the platform and my experience is very much like the
parents. The documentation appears to be almost completely missing. The built-
in documentation does not appear to include any guides at all. The API
documentation is largely the kind where the description is a more verbose form
of the method name, and sometimes when Objective-C is selected the
documentation is showing the Swift version.

~~~
mmusson
I have discovered that the previous documentation is still available in a
“documentation archive” complete with banner warnings about how it is out of
date and unsupported. It is almost impossible to find topics except by using
google search. Newer functionality is missing and some of it is no longer
accurate, but it is better than nothing.

~~~
topherPedersen
I've had to resort to referencing the documentation archive before as well.
While the new docs are certainly prettier, the old docs were much more
substantive.

------
no_wizard
I actually agree whole heartedly with the intentions behind this article. I
find Apples documentation to be incomplete and not nearly as detailed as I
think it should be.

I think that personally it’s not all that well organized either.

My minimum standard for good documentation has and always been Python’s[0].
While no documentation is perfect, I think they mostly get it right by
providing good explanations and examples consistently throughout the
documentation. I also like how it’s spilt up between modules and the code
examples are routinely updated. I have found very little issue with Python’s
docs. While it could definitely use more examples and and deeper content
around asyncio in some parts (mostly around transports and protocols) on the
whole its very good, to me it’s what all organizations should strive for at a
minimum. I also want to call put Mozilla’s Developer Network (MDN)[1] as
stellar, I reference and use it all the time and have genuinely been happy
with it.

To be fair in assessments, I’ve also found links in Microsoft’s documentation
that often link to things they have already marked as outdated or not going to
be updated, or just don’t work like the GitHub links on this page:

[https://docs.microsoft.com/en-us/xamarin/xamarin-
forms/user-...](https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-
interface/controls/views?WT.mc_id=docs-dotnet-xamarin)

So I think a lot of documentation around the big platforms especially have a
lot of work to do. This isn’t to say documentation is easy though. I sincerely
hope that all this noise just means it becomes more of a priority. I know from
experience that writing good documentation is hard and I don’t want this to
come across like I’m faulting anyone in particular or organization in
particular. I imagine with large and ever changing platforms it’s quite the
challenge. I just wanted to point to some examples I believe get it right most
of the time.

[0][https://docs.python.org/3/](https://docs.python.org/3/)

[1][https://developer.mozilla.org/en-US/](https://developer.mozilla.org/en-
US/)

~~~
userbinator
_I’ve also found links in Microsoft’s documentation that often link to things
they have already marked as outdated or not going to be updated_

IMHO that's usually a _good_ sign --- that the API you're using is not ever
going to change again. MS values stability and backwards compatibility far
more than others (and in the past, that was even better) so "not going to be
updated" means "this has become mature and stable, don't worry about
unexpected changes."

~~~
no_wizard
Then why mark the documents as deprecated?

~~~
userbinator
MS uses "deprecated" as a marketing term, but their backwards-compatibility
commitment normally do not allow them to actually break things this way.

------
danielinoa
Funny thing is Microsoft has much better documentation on Apple's very own
frameworks. Simply compare their documentation on this arbitrary type
(CIAffineClamp):

Microsoft's Documentation: \- [https://docs.microsoft.com/en-
us/dotnet/api/coreimage.ciaffi...](https://docs.microsoft.com/en-
us/dotnet/api/coreimage.ciaffineclamp?view=xamarin-ios-sdk-12) \-
[https://docs.microsoft.com/en-
us/dotnet/api/coreimage.ciaffi...](https://docs.microsoft.com/en-
us/dotnet/api/coreimage.ciaffineclamp.-ctor?view=xamarin-ios-sdk-12)

Apple's Documentation: \-
[https://developer.apple.com/library/archive/documentation/Gr...](https://developer.apple.com/library/archive/documentation/GraphicsImaging/Reference/CoreImageFilterReference/index.html#//apple_ref/doc/filter/ci/CIAffineClamp)

------
butuzov
This comment has nothing to do with apple, but about documentation in general.

I was trying to get into Kubernetes world via kubeflow, a machine learning
platform that works on top of the Kubernetes. Well, I have run into a bunch of
the missing examples, outdated articles, and things that just don't work (all
of that in official documentation).

I decide to change this a bit and start working on a small tool [1] that can
help check documentation (at least reduce deadlinks in the documentation, when
someone moves git files or just original source of info dies). Since I start
working on it, I meet only one project without issues, all others.. well, they
all had issues.

Maybe one day I post it on HN as a standalone link, but now here we go [1]

[1]
[https://github.com/butuzov/deadlinks/tree/develop](https://github.com/butuzov/deadlinks/tree/develop)

------
Amorymeltzer
Last week's ATP[1] had a segment on this, in particular a discussion of
[https://nooverviewavailable.com/](https://nooverviewavailable.com/) which has
an estimated breakdown of what percent of each framework has documentation.

1: [https://atp.fm/episodes/349](https://atp.fm/episodes/349)

~~~
czr
timestamped link:
[https://overcast.fm/+R7DXB8Hbs/14:08](https://overcast.fm/+R7DXB8Hbs/14:08)

------
edw
Nowhere in the comments thus far has anyone pointed out that SwiftUI — the
framework in TFA's crosshairs — is in beta. I've written a relatively large
amount of SwiftUI code and I get the impression that the design is still in
flux. There are corner cases (as well as much more mainstream one) that
haven't been fully thought through. Beta 5 of Xcode 11 brought non-trivial
changes to the API and I expect those to continue.

"It's not finished until it's documented" is a fine sentiment, but I don't
think Apple has remotely claimed that SwiftUI is finished.

~~~
oflannabhra
As I noted in another comment, the documentation for SwiftUI is actually
pretty good, especially if you take into account how quickly the framework has
changed. It includes some rich, progressive tutorials. [0]

The author states that they are planning to write an app from scratch with
SwiftUI. I think most iOS developers would hesitate to build an entire app on
a beta framework.

[0] -
[https://developer.apple.com/tutorials/swiftui/tutorials](https://developer.apple.com/tutorials/swiftui/tutorials)

~~~
chriskrycho
These tutorials are great (when they're working! That's been a bit
spotty)—genuinely great. But they don't make up for everything that _isn 't_
present. Take a step off that beaten path and you're in for a world of pain
today.

------
rubyn00bie
It's funny to read this and have it compared to Ember's docs, especially since
I've been using Chris's site a fair bit over the past few months...

I only bring this up for posterity, but Ember's documentation is terrible, and
what is even worse is the Typescript documentation is almost unusable its so
outdated. Chris's site is the only place you can go to find anything and it's
incredibly difficult to make sense of or is already completely outdated...
There are constant gotchas and missing documentation or things that are flat
out wrong...

I can understand complaining some about Swift's docs (though I've never had
that problem), but comparing them to Ember's seems like an awfully bad take.

P.S. I love Ember, learning it has just been nightmarish at points for almost
no reason.

~~~
chriskrycho
1\. You should file issues against Ember's docs! We have different experiences
of it for sure. Even just as experience reports, I know the folks who work on
it would love that.

2\. The Ember TS stuff _is_ in need of an update—desperately—as are my
(several-years-old-now!) blog posts. Unfortunately (unlike Apple) none of
those of us who work on it get _paid_ to do so at the moment – at all,
including docs. I'd _love_ it if you opened issues against the ember-cli-
typescript repo about specific issues/confusions you've had.

~~~
rubyn00bie
1\. Totally, I have, will do more, and would like to...

One big difficulty I've had, because I want to fix things (like docs), is
because everything post 3.12 is geared towards Octane and those docs are all
quite a bit different than everything before it... (and I'm on 3.12) it makes
finding the code to change, text, blob pretty difficult (IMHO) since master is
mostly Octane.

2\. I know you aren't paid and you're a saint for all you've contributed!
You've helped me an insane amount, and I want to say "thank you," for it. I
wasn't trying to give you too much shit, I just thought it was a little
funny... Ember's docs are in disarray for a new language and design patterns,
and so are Swifts! ;) I probably should've used a softer word than "awful," my
apologies.

2.1 I'll see you in your issue tracker later today :)

Thanks for being friendly! I super appreciate it, and for letting me know
about it being cool opening those kinds of issues. A LOT of Github repos are
hostile to _any_ questions at all (i.e. "go to stackoverflow or take a hike");
so, I tend to not make issues and only PRs.

~~~
chriskrycho
The Octane transition is indeed a big one!

As for being welcoming and friendly—of course! We _desperately need_ the help,
esp. to hit the gaps that we're blind to because we're used to working around
them. And honestly, "awful" isn't far off from how I would describe our docs;
doubly so far anything related to Octane with TS (where it's subject to
precisely the critique I leveled in this post: they don't exist!). See you on
the issue tracker!

------
cyberferret
Still? It has been a while since I have done any Apple platform specific
native development, but I remember about 5 or 6 years ago writing an iOS and
OS X app for communicating with an audio modelling device, and the
documentation for CoreMIDI was woefully lacking.

I couldn't believe that a part of the Apple operating systems that had been
ingrained for years had so little documentation and examples at that time. I
ended up finding out more from a lot of third party blogs and via forums.

I haven't checked, but are things like the MIDI framework still badly
documented in the Swift docs?

~~~
AlanYx
>I haven't checked, but are things like the MIDI framework still badly
documented in the Swift docs?

Documentation for the entire audio stack has actually gotten quite a bit
worse. Many references have been removed without new replacements being
provided. In many cases, there are broken links in what little documentation
remains. (For example, TN2274, which describes the USB audio stack is still
around, but several of the outgoing links, for example the documentation for
developing a USB audio plugin, are now broken, with the sample code deprecated
and removed with no replacement.) New frameworks like AVAudioEngine simply
don't document important limitations, particularly for OS X.

The Core Audio mailing list used to be a good place to get help and answers in
cases where the documentation is weak, but traffic has withered and no from
Apple seems to reply to messages any more. There has been a total of only four
messages on the mailing list this month.

It's really a shame, because the audio stack is well-designed, but the
documentation is so poor except for the basics that newcomers would have
difficulty getting anything tricky off the ground.

~~~
gdubs
What makes it particularly hard is that the Core Audio folks are a C++ crowd,
so they use a bunch of design patterns that don’t really make any intuitive
sense if you’re familiar with the other Apple frameworks.

Audio developers starting today are fortunate though because there’s AudioKit,
which is the right choice for the vast majority of apps.

~~~
AlanYx
AudioKit is quite good, but it's a third-party solution that covers a fairly
defined problem domain.

And while the AudioKit devs are among the most experienced Core Audio
developers around, even they are frustrated by the lack of documentation. See,
e.g., [1], where they say:

"The most important example of this is that we don’t really understand at
present how to create AUs which have polymorphic input and output busses.
[snip] This is fundamentally because the Apple documentation on how this is
supposed to work is essentially non-existent. I undoubtedly leverages the fact
that the input and output busses are KVO compliant, but this is about as much
as we know. We will have to figure it out via experimentation."

[1]
[https://github.com/AudioKit/AudioKit/blob/master/docs/AudioU...](https://github.com/AudioKit/AudioKit/blob/master/docs/AudioUnitCreation.md)

------
non-entity
I haven't done a lot of work in Apple ecosystems, but what I have seen from
their docs are admittedly pretty bad. Recently out of curiosity, I tried to
figure out how macOS drivers are written and left more confused than I was
before. Microsoft iirc, used to have their docs terribly organized (it was
difficult for me to find what I wanted without a Google search) but they seem
to have improved that nowadays

~~~
pmjordan
Driver development docs on macOS largely haven't been updated in 10+ years. I
started doing macOS kernel stuff when Snow Leopard was the latest release, and
the only documentation I can think of since then has been sample code for
Audio Server Plugins (for writing new-style audio drivers) and headerdocs
explaining the transition from IOUSB* to IOUSBHost* APIs. Any additional
information has been buried in a bunch of WWDC session videos, or you have to
extract it from Apple by filing DTS incidents.

On the other hand, Apple have decided a bunch of documentation was out of
date, so they've simply made it harder to access by burying it in archive
sections or taking it offline altogether, without providing replacements.
Getting into driver development now is almost certainly a lot trickier than it
was back then.

~~~
saagarjha
I hope Apple credited you the DTS incidents back for something like that!

~~~
pmjordan
They have credited a bunch of DTS incidents back, but that normally only
applies where they determine that they either:

* can't help you

* don't want to help you

TBH, compared to the person-hours required to write up the DTS incident in the
first place and keep the conversation going, test out their responses, etc.,
the cost of the incident itself is minimal.

Let alone the cost of the times where I decide to go it alone and figure it
out by trial & error or reverse engineering…

------
strictfp
Apple payments APIs are the worst APIs I've ever worked with. They're
inconsistent, badly documented, have unannounced breaking changes and contain
so many gotchas it isn't funny. For example, some of the most relevant data is
attached to the response but isn't officially supported and may or may not be
correct.

It's not exactly fun to code up payment integrations, and so I was kind of
hoping to get it over and done with. But with Apples payment APIs, we needed
months of production data to figure out how to use them without shooting
ourselves in the foot.

Using the API felt like interfacing with some badly configured eventually
consistent MongoDB cluster that a bunch of juniors stuffed full of receipts,
using the entirely wrong data model.

~~~
kalleboo
And what's worse is the "sandbox" for testing behaves completely different
from the real store, and has random undocumented downtime and bugs that you
only find out about from other people reporting it on the developer forums.
And creating, logging in to, and keeping sandbox accounts from contaminating
your real devices is also a PITA.

------
Phillips126
Docs are always something I evaluate before moving forward with a specific
tool or language for a project. I have not done much work in the Apple
ecosystem but it surprises me that a company of this size would have
lackluster docs. It makes me wonder how many non-Apple developers give up on
their idea for an app due to frustration and how that translates to lost
profit for Apple given their 30% cut.

I am not a huge Golang fan but recently I found myself using Go quite a bit
and I really appreciate their docs which include a description of each
function and an example. The example code is even editable with a "Run" button
so you could test and understand the function much better before moving it to
your own code. Here's an example if you are unfamiliar with Golang docs (click
the "example" link for the editable code):
[https://golang.org/pkg/strings/#Compare](https://golang.org/pkg/strings/#Compare)

------
thfc06
This is exactly what I've been dealing with for the last month, as I attempt
to completely re-write an Electron app in Swift. The part about scavenging
through WWDC transcripts particularly resonated with me. Coming from JS
ecosystem, I was also shocked at how few google results (even stack overflow)
would come up for issues I was running into.

~~~
rayascott
What annoys me about Apple, is that clearly their time is valuable to them,
but us paying Developer Program members are forced to waste days worth of
business hours hunting through their appallingly maintained "documentation".
And that really pisses me off.

------
gnachman
The comments in header files are often the only (or only useful)
documentation. So don’t give up before looking there. Sometimes they wait a
few years to write docs. For example, NSWindowAccessoryViewController went
undocumented for three or four years. Which was fine because it was too buggy
for me to use anyway. The docs are enough to get you started but it’s only
brutal experience that teaches you how to use things. In practice you spend a
lot of time working around bugs and design flaws. Those will never be
documented, of course.

~~~
WWLink
Yeah, I developed software for a platform that isn't documented anywhere at
all on the internet, and the documentation it comes with is sketchy.
Discovering a new widget and spending time messing around with it was the
norm.

------
coldcode
I've spent most of my programming life doing Apple stuff (in between Java and
C++ non Apple stuff too) and the only really good docs they ever had was the
old paper Inside Macintosh in the 80's. Even when I worked at Apple at DTS in
the mid 90's we had to hire someone to go around to every engineering dept and
find out wtf they just shipped to provide developers something, anything, as
documentation. That was back when Apple lost tons of money. Now the excuse
can't be financial. Maybe they don't care enough?

------
fortran77
It's always been bad, too! Back in the OS9 days, the Apple documentation was
"cumulative". You had to know every trick, every hidden bit and flag, back to
day 1 in order to write a program.

It's no better today. People who live isolated in the Mac universe have no
idea how good Microsoft Visual Studio tools are, and how complete and thorough
the documentation is, and how consistent the API is. You don't have to wade
through a 30 years of legacy APIs to get anything done.

~~~
heisenbit
Woz documented every line of his Apple ][ system monitor code and it was a joy
to read.

~~~
fortran77
Yes! I've been around since those days.

------
hugey010
I've developed native iOS and Android apps professionally since 2012 and I
always found their docs to be a mix of amazing -
[https://developer.apple.com/design/human-interface-
guideline...](https://developer.apple.com/design/human-interface-guidelines/),
and fairly useless -
[https://developer.apple.com/documentation/vision](https://developer.apple.com/documentation/vision).
All example code I've seen provided by Apple looks like a Fisher-Price® My
First UIViewController toy.

It is my belief that the Apple iOS docs are just another barrier to developer
entry; similar to their $100 yearly license, expensive hardware combined with
their WYSINWYG simulator, and woeful iTunesConnect experience.

These barriers to entry, including the poor documentation, definitely have
some interesting affects on the ecosystem. I've seen examples of all of these
in the real world.

    
    
      * Experienced iOS devs have a shared trial by fire experience.
      * iOS salaries are slightly higher on average compared to Android.
      * Skilled iOS devs tend to be excellent developers in general.
      * Average iOS devs can be more arrogant and less likely, or less capable, of helping out in other languages and projects. (Apple framework specialist pigeonhole principle)
      * There is almost zero culture or standards regarding application architecture or documenting iOS apps.
      * Underlying "older" concepts like memory management have been masked, forgotten, and / or ignored.

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

[0] -
[https://developer.apple.com/library/archive/navigation/](https://developer.apple.com/library/archive/navigation/)

[1] -
[https://developer.apple.com/library/archive/documentation/Co...](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CoreData/index.html#//apple_ref/doc/uid/TP40001075)

[2] - [https://nooverviewavailable.com](https://nooverviewavailable.com)

[3] -
[https://developer.apple.com/documentation/swiftui](https://developer.apple.com/documentation/swiftui)

[4] -
[https://twitter.com/akashivskyy/status/1187790245804367873](https://twitter.com/akashivskyy/status/1187790245804367873)

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

~~~
pdfvshtml
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!

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

------
microtherion
OPs criticism is definitely justified, and it makes me sad. In my opinion, the
peak of Apple documentation was the new, refactored edition of "Inside
Macintosh" in the 1990s:
[https://en.wikipedia.org/wiki/Inside_Macintosh](https://en.wikipedia.org/wiki/Inside_Macintosh)

Not only is there not enough information, but the documentation team goes out
of their way to reorganize what documentation exists every couple of years, so
outside links into the docs constantly go stale.

------
tempodox
Apple's developer docs have been incomplete since the introduction of OS X. I
don't expect it to get any better before hell freezes over. The article
mentions that this makes it hard for newbies to learn. That's true but my
guess is that by the time those chickens come home to roost, JavaScript will
be called a systems programming language.

Edit: Updated wording to article's title change.

~~~
iainmerrick
I wouldn’t put it quite as strongly as that, but yes, the OS X docs have never
been great.

It’s a shame, because the classic MacOS docs were _amazing_ , amongst the best
technical docs of all time at their peak. (I had a shelf of Inside Mac books,
and they were useful for years.)

------
TheKarateKid
I’m surprised no one has complained about the lack of documentation for
Safari, especially on iOS where special behavior is done for mobile.

The best I could find from Apple was several years old, and clearly not up to
date as the behavior no longer functioned as documented.

~~~
saagarjha
There is this:
[https://developer.apple.com/library/archive/documentation/Ap...](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002051-CH1-SW1).
Not sure if this has what you'd need.

~~~
TheKarateKid
Came across that, but it's terribly outdated. Bottom of the page even says
last updated in 2016.

------
rasta78
It's unclear to me how this post made to the top when it references SwiftUI -
a framework which is still in beta and shouldn't even be brought into
discussion. On the other hand, UIKit is documented about ~90% which is an
insane amount and this is what most of the iOS devs are using on a day-to-day
basis.

------
novok
Apple under invests in developer tooling relative to what it does. The dev
tooling teams are surprisingly small and the internal dev experience at apple
for their own employees is pretty bad compared to other large tech companies.
My guess partly is because of the siloed nature of the company, and they don't
sell dev tooling for "money".

------
russellbeattie
Every once in a while I think to myself, "I have a problem with OSX, I think
I'll try to automate it with JavaScript for Automation (JXA)..." You know the
rest.

The astounding lack of documentation is almost amusing. It becomes an
adventure of trying to convert old AppleScript examples into JS, spelunking
into GitHub and StackOverflow and general trial and error until I get
something to work.

All this said, I'd rather have functionality without documentation, than the
extreme of not launching an API without proper docs.

The solution of course - though Apple would never do this as it's not in their
DNA - is to let devs add to their docs like PHP does. I'd be happy to add back
a few examples to their site once I figured things out if that option was
available to me, but right now there's really no central place for this
besides random forums or starting my own repo.

~~~
saagarjha
Nobody seems to use JXA, unlike some of the technologies that are heavily used
but just as undocumented :(

~~~
russellbeattie
I don't disagree, but you might be confusing the chicken and egg. Maybe if
Apple actually documented JXA... (it's actually quite useful).

~~~
saagarjha
I know it is, but I have little hope that it ever will. Everything I've heard
points towards the OSA team not doing so hot these days.

------
carapace
Funny meme on the wall at Google: Picture of Governor Tarkin on the Death Star
captioned, "Documentation? At our moment of triumph?" Still makes me laugh.

------
lasermike026
If there is a problem with Apple documentation issue a bug report. I'm not
from apple but I worked in their ecosystem for some time. When you experience
real problems your manager or CTO might have to get in touch with a managing
director. If you go to WWDC make sure you complain directly to the guys
wearing the checkered shirts. They are the ones in change. The cool thing
about WWDC is that you can communicate directly with Apple developers. They
will even look at your code to help.

~~~
saagarjha
> When you experience real problems your manager or CTO might have to get in
> touch with a managing director.

If you can…

> If you go to WWDC

Again, if you can…

------
jrochkind1
15+ years ago, Apple had some of the BEST documentation. But I agree it's
fallen precipitously.

~~~
Ididntdothis
I worked a little on the Mac in the 90s and then their documentation was
really good. You could read it like a book. Actually Microsoft was really good
back then too with the MSDN library CDs they shipped. Not it’s pretty bad and
getting worse all the time with a lot of broken links and tons of auto
generated content that doesn’t explain the big picture.

------
perfectstorm
So much this. The other day i was trying to look up documentation for Swift’s
KVO and i couldn’t find one. I know there’s a KVO API that accepts a closure
but i just couldn’t find where it is. smh.

Apple used to link sample code with pretty much all the big APIs but they no
longer do that. If you want to see how an API is used or see the best
practices you’re better off checking stackoverflow.

~~~
saagarjha
You're looking for NSObject.observe(_:options:changeHandler:), which doesn't
seem to have a dedicated documentation page that I can find but it's mentioned
here:
[https://developer.apple.com/documentation/swift/cocoa_design...](https://developer.apple.com/documentation/swift/cocoa_design_patterns/using_key-
value_observing_in_swift)

------
oh_hello
Apple's developer guides were amazing. I was able to read through them and
become a proficient iOS developer. They are now archived and not updated. Even
with experience on the platform, I now often find it hard to navigate the docs
and learn major new frameworks. It is a real shame.

------
CalChris
For a company with a capitalization of $1.123T, yeah, Apple is pretty cheap on
the developer documentation.

------
boris
Their diagnostics is pretty cool, though. How about this gem:

    
    
      ld: warning: ignoring file build2/libb.u.a, building for macOS-x86_64 but attempting to link with file built for unknown-unsupported file format
    

Going to steal that "unknown-unsupported" term for sure.

------
ngcc_hk
Reading hundred comments and the op is about the lack of documentation. Swift
is a good language to learn but api no. The discussion might explain it. But
should there be one to address that issue as an ecosystem.

For example ask Apple to do something and let them sort that out using their
employee. Or some web site (I use one particular to help me).

Swift is a language like lisp or clojure. You may look at its architecture etc
to see whether it is built in issue (lisp is easy but its library is not,
say). Or it is really just a hiring issue.

Or may I just ask how to address the original question if it is just language
lack of good doc.

------
devin
As someone who has only recently gotten into producing an app for iOS, I was
immediately struck by the lack and quality of the docs. It’s nice to hear that
I’m not alone.

The lack of documentation led me to feeling like I was just somehow personally
missing something. I’ve been at this for awhile and the apple docs left me
feeling like a junior programmer all over again. I wanted to first blame
myself, but it’s become clearer to me that Apple just doesn’t care about
supporting devs. That’s the theme for years now and it only seems to be
getting worse. Bummer.

------
OliverJones
Agreed this is a big problem. Sometimes sitting through a WDC tutorial video
can unearth answers. But, really?

You know, they could call Tim O'Reilly and commission a bunch of excellent
books. They have the money and Tim has the writers.

------
supernes
Developer goodwill is not really that essential to a lifestyle accessories
brand.

~~~
scarface74
Right because 50% of the US mobile market only buys a phone because it’s an
“accessory”.

~~~
supernes
People would still buy iPhones even if Apple decided to purge 99% of apps from
their store.

~~~
ahbyb
Which would make sense since 99% of apps probably have fewer than 100
downloads each.

(Yes I know this is not your point, just a little joke)

------
meh206
They're too big to care.

------
catchmeifyoucan
Might just be me - but I'm attracted to well formatted docs. It's not a
dealbreaker but I do appreciate when the fonts, spacing and code snippets are
well thought out

------
gigatexal
According to Marco of overcast and the ATP podcast fame the docs pertaining to
the audio subsystem is really lacking.

------
smacktoward
Apple's just doing with documentation what they do with everything else:
making it thinner at all costs.

------
specialist
Sample code (showing usages) and tests are also part of the documentation.

------
ChrisMarshallNY
Some time ago, I was contacted by Apple to apply for a job. My code is
insanely well-documented. I like to think that a lot of the inspiration for my
code docs comes from Apple's open codebases. Their code is exceptionally well-
documented.

In any case, as is usual with all employers, these days, they completely
ignored the focused, relevant links that I sent them to elements of my
extensive portfolio of repos, and, instead, based the entire interview on a
50-line binary tree test in Swift.

I'll make it clear that I'm NOT a fan of these. I am mediocre, at best, at
them, as I don't come from a traditional CS background (I started as an EE).

In any case, during the test, I did what I always do when I write code. I
stopped to write a header document for the function.

This was clearly not something the tester liked. Also, to add insult to
injury, they dinged me for not writing a cascaded nil-coalescing operator. The
code they wanted me to write was difficult to understand, and absolutely not
one bit faster.

What makes this even funnier, was that this was for an Objective-C job, and
the links that I sent them (that they ignored), were to ObjC repos.

After that, I just gave up on them. It kind of shows where a lot of this is
coming from.

Dynamically-generated documentation can be great (It's clear that the lions'
share of Apple's developer documentation is dynamically-generated), but it
requires a VERY disciplined coding approach. I suspect that they may be hiring
less-disciplined engineers, these days.

~~~
jtchang
What is a "cascaded nil-coalescing operator" ?

~~~
ChrisMarshallNY
Think the ternary operator, but worse.

In Swift, this is expressed by "??".

It means "If the previous test returns nil, then execute what is after the
??".

For example, if you have a concrete Int, but the source might be an optional,
then you could do something like this:

    
    
        let a = b ?? 0
    

That means that if b is nil, then set a to 0. Otherwise, set it to whatever
value b has.

You can chain these, like so:

    
    
        let b: Int? = <something from somewhere>
        let c: Int? = <something from somewhere>
        let a: Int = b ?? c ?? 0
    

So you have a couple of optional values coming in, but they could be nil, so
you chain them.

You can have a lot more going on in the handlers than simple assignments, but
this gives you an idea.

~~~
accatyyc
In Objective-C (and some other languages with ternary operators) the same can
be written like this:

    
    
        int a = b ?: c ?: 0

~~~
WWLink
That one's straight up called the Elvis Operator.

I hate it when things like this get names that everyone's supposed to know and
it's considered a mark against you if you've never heard it before, but I do
think the name Elvis Operator is hilarious. :D

~~~
toxik
I was wondering why the funny name, and

> The name "Elvis operator" refers to the fact that when its common notation,
> ?:, is viewed sideways, it resembles an emoticon of Elvis Presley.

[https://en.wikipedia.org/wiki/Elvis_operator](https://en.wikipedia.org/wiki/Elvis_operator)

------
mlang23
One Cook can ruin many meals.

------
balls187
My issue with this is that the developer is comparing his experience with
Apple's documentation over a few months, with his anecdotal experience over 4
years.

Part of gaining experience with a platform is the ability to source answers to
technical questions effectively, including how to use official documentation
effectively.

~~~
chriskrycho
I'm _extremely_ comfortable reading documentation for a _very_ wide variety of
platforms, languages, etc. (The first software I ever wrote was Fortran via
`gfortran`. Trial by fire!) It's not just me. This is just straight-up
_absent_ :
[https://nooverviewavailable.com/swiftui/](https://nooverviewavailable.com/swiftui/)

As I noted in the post, I'm getting by _anyway_ … but it's more work than it
needs to be, and more work/worse state of docs than other ecosystems I've
learned in similar amounts of time.

~~~
balls187
My comment wasn't about your comfort level. It was about comparing your
experience 4 months in, to your experience 4 years in, _anecdotally_.

~~~
chriskrycho
Erm, yes. Any possible comparison anyone could do of their own experiences
would _by definition_ be anecdotal.

I also know exactly what my first 4 months in other ecosystems were like.
Including picking up Fortran! That was rough! :)

------
jmull
The Swift language has excellent documentation.

For SwiftUI, the WWDC presentations are essential, IMO, for the high-level
stuff. There is basic reference documentation, but there's no way to put it
all together without a high-level understanding. It follows the patterns of
some other frameworks so depending on your experience you may be able to get
by without the WWDC presentations, but I'd still watch them or at least read
the transcripts.

I think Swift Package Manager is meant as a community tool, and the love and
care it needs to become excellent is not going to be coming from Apple, not
without some kind of strategic change. Either the community will value it and
figure out how to move it forward or it's not going to get much better. I
could be wrong -- I'm trying to judge it's on-going strategic importance to
Apple -- but I think the way it's going to improve is through community
involvement.

Anyway, I'm not sure what the point of this kind of rant is. Whining about
Apple is an easy way to get useless internet karma points, but it's such a bad
look for a developer. At least half the job is being the one who finally deals
with things someone else probably should have already dealt with but didn't.

~~~
chriskrycho
Noted the first two bits _in the post_. Did you read it? :)

As far as SPM goes: they've got it built into Xcode at this point, and are
doing WWDC sessions about it. At what point does it become "official" enough
to warrant "This needs to be better" criticism?

As far as "useless internet karma points": I couldn't care less. History has
shown that when people make enough stink about this kind of thing, it
sometimes—rarely, but sometimes—gets to the ears of people high enough in the
management chain that it ends up shaking things loose at the mid-level spots
where poor decisions around these things tend to get made.

I don't work at Apple. I _can 't_ go fix most of this stuff. In my day job, I
spend a _lot_ of time on these kinds of concerns. In this context, though, the
only thing I _can_ do is shout a bit and hope it shakes things up a bit.

~~~
jmull
> Noted the first two bits in the post. Did you read it? :) Yes, I did read.
> Come on. However, you're not quite right. You called Swift "relatively well
> covered". I disagree with that and consider the Swift language documentation
> excellent. That's not really the same thing.

I did see you mention the WWDC videos, but I think you mischaracterize the
role of them. My point is, people who are interested in learning SwiftUI
should _start with_ the WWDC videos, not feel "reduced to searching through"
them.

Anyway, if you want to work on top of something solid, forget about SwiftUI.
It's very raw and changing fast. I wouldn't rewrite on top of it now unless
you aren't planning to release for at least a year. And you might end up
throwing it all away anyway.

And shout all you want. I'm letting you know it's a bad look.

~~~
chriskrycho
To be clear: I've watched every SwiftUI video. They're _great_! They just
aren't the same as _docs_.

As for the look: I understand the take. We obviously differ on whether it's
ever appropriate to make some noise this way. For my part, when it's come _my_
direction (as it has a couple times in the Ember ecosystem), I've appreciated
it.

