No Overview Available: A Survey of Apple Developer Documentation

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.

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.

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

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

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

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

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.

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.

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

Ah, the joys of audio programming