A concrete example of why Apple's documentation is terrible

Apple's documentation is famously dreadful. In particular, it is often missing or incomplete. No overview available provides some statistics on this, but I believe it actually understates the problem. Even when documentation is available, it is often terrible. Here is a small, concrete example I recently encountered while doing some macOS development (an area I'm less familiar with).

I wanted to prompt the user to open a directory. How does one do that? Obviously, I Googled it (adding Swift to the search query to avoid ancient Obj-C answers).

It seemed like I needed something called NSOpenPanel.

I found Apple's documentation, and it seemed fairly clear. I configured it with some straightforward options.

Okay, how do I actually use it?

Hmmm. That was far from clear. There was literally nothing on the page that explained even the most basic use case. Sigh. I hit Google again and found that I needed to call begin, which accepts a callback that receives a result.

The example was outdated (a perpetual issue with Swift), but I eventually sorted that out in the editor (we now have a nice enum for the result).

Okay, but how do I get the actual directory selected? The success value was .OK. Was there some kind of data associated with that? No. Just a result.

Hmmm...

There is a delegate that I could set. Maybe that would provide the result.

I wasted a few minutes on that; it basically appeared to be for configuration.

Ah, it inherits from NSSavePanel! That was not at all obvious (and I'm sorry, OOP devotees, that makes damn all sense in principle). Oh, look, loads of new functions and properties. Ah, so I was meant to query the NSOpenPanel object for the directory.

It wasn't really clear how. Xcode offered url, urls, directoryUrl, representedUrl, among others (I'm not making any of those up, and most didn't seem to be in the documentation). Let's be optimistic and choose url. Success! It appeared to work.

Oh, also missing (before I continue): in recent versions of macOS, one needs to add a capability for reading (and writing) to user-selected directories. This was again completely missing from the documentation and yet another frustration for someone not already very familiar with the ecosystem.

This can be so much better. Apple developers may sneer at Electron, but look at how clear Electron's open dialog documentation is.

What goes wrong with Apple's docs?

  1. Missing and incomplete content.
  2. Outdated information (Obj-C or older Swift versions are common in documentation).
  3. Poorly written explanations that assume a level of familiarity rendering the documentation unnecessary for those who possess it. Lack of clear explanations.
  4. Absence of examples for even basic usage.
  5. Badly designed, legacy OOP APIs: Swift can sometimes compensate for poor documentation through strong typing. Sadly, many macOS APIs are a blend of old-fashioned OOP with surprisingly low-level details.

What if you are doing Apple development?

Avoid Apple's documentation (even when it appears as top Google results), as it will likely be pretty bad. Stack Overflow is sometimes helpful (but often contains outdated Swift versions). Some third-party documentation sources are good (e.g., Paul Hudson, Ray Wenderlich).