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