
No Overview Available: A Survey of Apple Developer Documentation - ingve
https://nooverviewavailable.com/
======
xhgdvjky
I have worked on native Windows and Mac UI, and in my experience, Apple does
document most symbols. It just does it really poorly. So percent of symbols
documented is not a good metric.

MSDN is much much more thorough. MSDN usually tells you everything you need to
confidently call a function... Apple docs tell you enough to start
experimenting.

Apple tends to have good textbook style documentation that doesn't directly
explain a symbol per se, but rather explains a topic e.g. how to write network
code on a Mac. But these pages are usually outdated... like 10+ years
outdated.

------
Hamuko
My biggest annoyance with Apple's documentation was depreciation. I'd find an
API that did what I wanted, but it had a note saying that it was deprecated.
That's it. No reasoning for it, no indication of what replaced it, nothing.

And if you searched for tutorials/examples on Apple's developer site, there
was a lot of stuff that was written for like 10.5 days. And if those
deprecated APIs told me anything, it was that they were probably not gonna
work as-is.

~~~
pornel
Around 10.5 I used to hold Apple's docs in very high regard. All the basics
well documented, with examples.

But they've redesigned the dev site a few times, and each time they've changed
the URL scheme (breaking all of external links), added more finicky
JavaScript, and seem to be losing actual docs.

Nowadays I just can't find anything. If I search the docs, I'll end up finding
scraps like some variant of an enum "kEnableFoo" at most documented as
"Enables foo.", and that's it. No links to what the other options are, the
functions which take it, no examples.

------
kemayo
Say what you will about PHP, I maintain that its language-documentation ruined
me for most other languages' attempts at the same.

~~~
shaki-dora
Agreed! PHP was the first language I learnt, and to this day I still feel like
I must be missing something obvious when getting lost in other projects'
documentation.

Case in point: python! I tend to find the C interface, or decades-old RFCs
long before I get to what I'm actually looking for.

Only language on a level with PHP has been Ruby.

------
pram
Documentation in general is pathetic these days. Remember when software used
to come with enormous, bound tomes? Even Apple used to provide like 10lbs of
documentation for Final Cut.

[https://www.flickr.com/photos/primeval/44956561934](https://www.flickr.com/photos/primeval/44956561934)

~~~
kuzimoto
I feel the primary reason is because things are updated so much more
frequently now. It's probably not worth the time to fully document software
only for it to become outdated shortly afterwards.

Whereas before, software came on CDs, and if you wanted to update you had to
just buy the next version.

~~~
Fnoord
I regard it as short-term greed. Documentation and QA doesn't sell short-term;
things like Sidecar do.

Perhaps the right way to tackle it is updating less frequently (feature-wise)
and focus more on stability and documentation instead. Because good
documentation is written by the engineers themselves, it means less output
from them (it is a myth that you can just throw more money and human resources
at the problem). Imagine, for example, macOS and iOS only being updated once
every 2 years with a major release.

------
jmfayard
iOS developers are pretty lucky if that's the biggest problem they have with
the official documentation.

Story time: I started my career in programming with Android development in the
years 2012-2014.

And it was quite painful.

In 2012, I thought that iOS and Android were going to be the two only huge
mobile platforms, and here I was right. I randomly chose Android because that
was the smartphone I had at that point.

I thought it was going to be cool. And here I was mistaken.

After some months, it became obvious that it was going to be hard. The
coolness effect disappeared quickly. I struggled a lot to write good Android
code. No matter how much I RTFMed, it seems that I was only able to copy/paste
things on a trial and error basis. Building the simplest feature
(login/subscription screen) took a looong time. The iOS colleagues generally
seems significantly faster than us (although they have their own rabbit
holes). I never (even now) understood how to make things look nice. But worse
than that it was never reliable.

The code I produced was hard to write, hard to understand, harder to maintain,
with traps everywhere. I went to Android conferences and the Android team
asked us: are you writing tests? I didn't dare to answer "not really" but that
was the truth. I RTFMed once more how to write tests on Android, but it never
made sense to me.

To give you some context, it was a number of years ago, I was a junior
developer and my colleagues were quite young as well. Things would be very
different if you start now and have the luck to have a good Android mentor to
guide you.

But what _I_ had was the official Android documentation.

And now that I am more experienced, I can see clerly that it was horribly
written.

Even today, it continues to mislead every new generation of developers in a
dark path.

The worst part is the so-called "Android Burrito Design Pattern" where you
just put _everything_ \- your business logic, your application lifecycle, your
views, you bindings, your threading, ... - in one big fat BurritoActivity or
BurritoFragment that wraps _everything_. Make the beginner mistake to believe
that the documentation writers know what they are doing, and use those samples
as a blueprint for how you should build things, and you are going to find
yourself in a very dark path indeed.

I wrote about it here

[https://dev.to/jmfayard/android-s-billion-dollar-
mistake-327...](https://dev.to/jmfayard/android-s-billion-dollar-mistake-327b)

------
dddddaviddddd
From the Read Me on GitHub:

> It's become a truism among iOS and macOS developers that Apple's
> documentation is often incomplete or missing altogether. > This project aims
> to provide some objective metrics for evaluating the quality and quantity of
> the docs on developer.apple.com/documentation.

[https://github.com/NSHipster/NoOverviewAvailable.com/blob/ma...](https://github.com/NSHipster/NoOverviewAvailable.com/blob/master/README.md)

------
CountSessine
Yup - almost everything with IO- at the front of it is below 50%. That’s a
pretty good reflection of how awful the IOKit docs are.

------
Fnoord
It is vital for _any_ process to have good documentation available. Lack of or
bad documentation makes me wonder about the rest of the product, especially
security-related, and longevity.

------
ponyous
Music Kit JS. Never knew this existed. Any notable apps built on top of it?
How do developers discover these kind of things?

~~~
pjmlp
You get to watch the juicy WWDC sessions.

------
blueboo
Ah, the joys of audio programming

