Apple Developer Documentation Is Missing

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

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/

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

Official documentation may be more important for a framework that is new, especially if it's one that developers are being required or encouraged to switch to.

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.

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.

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.