Specifically, he claims: that large portions of the Swift user interface API are entirely undocumented; that he was unable understand the full capabilities and limitations of the package manager through reference to its documentation; that he finds himself frequently searching video transcripts to find information unavailable in the documentation.

I think that, if these claims are true, it does not reflect a good state of affairs, and that the extra work imposed on the individual developer is worth complaining about.

I don't think that he is calling out the work of the technical writers in any unsociable or shameful fashion in the text of his blog post. I agree that 'garbage' is not a good metaphor for "woefully inadequate," as it implies that the existing documentation would be better disposed of than referred to. However, I think that when dealing with a large software corporation that has teams dedicated to writing and maintaining technical documentation, it is not especially cruel or unfair to use hyperbolic language in calling extraordinary lapses to public attention.

The actual, in-production APIs are documented.

I’m a fucking awful violin player, but I know unskilled/professional playing when I hear it. Is the implication that I have no room to complain when I buy a ticket and the performance is bad?

Here’s one obvious example that comes to mind: how do I turn on the GPS on iOS? This is documented nowhere. The answer is that location requested with an accuracy above 100 meters will use cell towers, below 100 will use WiFi geolocation, and below some other threshold (10 meters? I forget) will use GPS. But that’s nowhere in the docs. They just tell you “use what you need”.

Here’s another one, what is the maximum size of a process’s address space on an iPhone? This one is not documented anywhere, you actually have to read the kernel source code to figure it out!

These are just two examples that popped into my head from ~3 years of iOS work. But they’re the rule, not the exception. Apple documentation tells you how to do basic and standard things the way Apple expects. It doesn’t give actual details of how things work.

As for 'how large is the maximum iPhone process address space', I don't really know how bad it is that you cannot easily find this documented. It doesn't really seem like something many apps need to know about, and highly specific to the iOS version and maybe even hardware it is running on. Not saying your app or whatever you are making doesn't need it, but I estimate this kind of information is irrelevant for close to 99% of apps. I don't think the iOS programming model is such that you can derive any kind of guarantees how much you can allocate from that number. What do you want to use it for?

As for what you might want to know the maximum address space size for: evaluating whether unattributable production crashes might be due to running out of address space.

That's not what I said, nor what the documentation said. From the documentation:

The system always tries to give you the best location data that is available, but these properties give the system the flexibility to turn off hardware elements when they are not needed. For example, if you set the desired accuracy to kCLLocationAccuracyKilometer, the system might disable GPS and use only the Wi-Fi hardware, which would save power and still give you a greater accuracy than you requested.

In other words: the system will not promote the returned accuracy if the data it has is already within the accuracy you asked for, but it will still fall back to whatever source of location data available, possibly higher accuracy, if no lower-accuracy source is available.

This makes a lot of sense, because it is much more common to only have a GPS signal, and no cell tower or WiFi geolocation (e.g. when doing outdoor activities) than the other way around. In that case your '1 km accuracy' app might in fact get you GPS accuracy. But if you are in Central Park, you will most definitely get location data from cell towers, so in that case your app will not promote the accuracy since you didn't ask for it. Ergo, if you need the highest accuracy, you have to ask for it. The documentation makes it very clear the accuracy parameter is not a tool to force a specific accuracy, but to allow the system to relax accuracy in favor of lower power consumption, if your app doesn't need it.

Not trying to be snarky here, but in this particular case it seems the problem is not in the documentation, but in your reading comprehension of it. Unless of course there is a bug in CoreLocation, or you got so unlucky when you tested in Central Park, that there was somehow not even a GPS signal available.

Huh? How is that not exactly the right answer? You tell the API how accurate you need it to be, iOS will get you that accuracy with the minimum energy consumption necessary.

It makes sense to not document the thresholds because they probably aren’t constants. (Or even if they are, they might not be in iOS 14.) It’s entirely possible that the accuracy of non-GPS methods may improve over time.

And they would certainly vary greatly depending on the environment. Who knows, if you’re in a concrete jungle with very dense wifi coverage, it could even be more accurate than GPS.

Conversely if you’re in a tiny rural town with one cell tower and no wifi, it might have to turn on GPS even if you only need 50 meter accuracy.

Apple is not a people. Apple is a TRILLION dollar megacorp. They can afford more.

Ignoring that out of kindness is silly. Any good professional should welcome honest feedback; if you can't criticize a $T company because it might hurt someone's feelings...

Complaining about the docs is important feedback, aimed at ultimately making Apple healthier. And getting to the point where the docs are sub-par means priorities have shifted over a period of years, and will take that long to get back in shape. That's not on any one person, not even Cook, except in the ultimate responsibility sense.

Secondary example is XCode, their IDE. It is painfully obvious they don’t have enough people working on XCode.

> the problem is not individual engineers — who are not responsible for writing docs; that is the responsibility of dedicated coumentation teams. But that does not make it any less a failure of Apple’s engineering organization.

If a team ("dedicated [documentation team]") is responsible for something, surely the individuals in such team are responsible too? Or the author is making a distinction between "engineers" and team members of documentation teams?

Sometimes having people critize « your » work in public helps you convice your manager’s manager something needs more care.

It is clear, from your username, you like Apple. But ask yourselves whether you are being fair to the OP here.

The following is a quote form the article

> Given what I know of Apple’s approach to this, the problem is not individual engineers — who are not responsible for writing docs; that is the responsibility of dedicated coumentation teams. But that does not make it any less a failure of Apple’s engineering organization. The job of an API engineering organization is to support those who will consume that API. I don’t doubt that many of Apples API engineers would love for all of these things to be documented. I likewise do not doubt that the documentation team is understaffed for the work they have to do. (If I’m wrong, if I should doubt that, because Apple’s engineering culture doesn’t value this, then that’s even worse an indictment of the engineering culture.) This kind of thing has to change at the level of the entire engineering organization.

It would be shameful if the author were calling out a particular person, because we do not know anything about any particular person who worked on these docs, what state they were in before that person got there, and what road blocks they might have.

However, it is not shameful at all to call out Apple as a company. The assumption is that if any company in the world has the resources to make their documentation amazing, it is Apple. The failure is not that of the people working on the documentation, it is that of the company as a whole.

2. Turns out that yes, I do prioritize documentation extremely highly when I publish projects for other people to use. See e.g. https://true-myth.js.org – and when we built this, we did not publicize it or ship a 1.0 till every single item was documented.

I'm not looking for perfect docs; that doesn't exist. It's something you can always improve.

I'm just looking for any docs.

And you know it's bad when Microsoft has better Apple docs than Apple has: https://twitter.com/akashivskyy/status/1187790245804367873

Swift UI’s error reporting is also obtuse.

Agreed. Calling something 'garbage' and providing no concrete examples isn't really constructive feedback. It is just name calling.

And this should be concerning. If Apple wants people to use Apple Sign In, they should do more than mandate its use. They should make it easy to implement, or, at the very least, provide clear documentation.

Instead, I've had to rely on other documentation outside of Apple that all start by sharing their disappointment with Apple's documentation on this subject, and then try to decipher what Apple is doing.

Some of the code samples/sample projects also regularly break. I wonder if Apple has any automation around that.

1. SPM has been out (and officially supported as part of the Swift Project) since Swift 3 came out. You can defend it as being "not part of normal development workflows for Apple platforms" if you like, but it has been officially supported for years. People would rightly call this out in any other language; it's fair to call it out here.

2. My very strongly held opinion, as I noted at the end of the article, is that you can't actually call something "shipped" until you've shipped the docs.

And you may feel that way about docs, but it is not reasonable to find one single rushed release, and use that as an argument against the entire ecosystem. That is not a reasonable argument.

I'm sure documentation will improve on both, and I've very rarely suffered from a lack of documentation when developing for Apple platforms. It has been a lot more pleasant to read than, for instance, Android documentation (although it has been a number of years since I did that, so it may have improved.)

This is sad, because if Apple wants Apple Sign In to succeed, you'd think they want to make this as easy to implement as possible. Instead, they relying on simply rely on mandating it's use in iOS Apps.

I think you're proving his point. Apple, and the larger Apple community, simple doesn't' care about people who don't drink the Kool-Aid, and they mock and insult dissenters (as you did).