And this reminds me of the documentation quality of Symbian around 2005-2007. I would highly recommend the author of the article the check it out, before lamenting Apple's documentation.
The Symbian documentation team was tiny, perhaps 20 people at most. At an offsite we would pretty much fit round two tables at most. As always you get what you pay for.
Even so the Symbian team did some pretty cool things such as creating open source documentation standards for C++ and the tools to support that.
Honest question: What's the purpose of the throwaway account for this? Is there some blow-back that you expect from this? Is there some NDA that precludes you from even talking about it years later? Do you think it reflects negatively on your years later?
>> The Symbian documentation team was tiny, perhaps 20 people at most. At an offsite we would pretty much fit round two tables at most. ... Source: I was there.
> What's the purpose of the throwaway account for this?
My guess is they want keep their other account pseudonymous, and admitting that they were one of a specific team of 20 people at a specific company goes a long way towards unambiguously identifying them. At a minimum, one of their teammates could probably ID them.
I'm not the person, but I had an HN leaderboard member pitch a tantrum at me about a programming opinion on here, and imply that my opinions were representative of my employer. It's a good reason to stay pseudonymous.
Another good reason, and a good reminder that popularity, status and/or power does not automatically rid a person of the human foibles that plague us all.
Ah, that's true, good point. As someone that has mentioned more than enough information to definitively identify myself online with this account, I guess I've adjusted enough that I didn't even consider that.
Seriously, Apple is one of the richest companies in the world (I don't remember if it's still The Richest or not). Similarly, Google's documentation is pretty bad, considering just how ludicrously rich they are. They could afford to hire entire teams whose only jobs were to write documentation and it would barely make a blip in their bottom lines.
In contrast, I've always found Microsoft's documentation to be incredible. It can often be hard to find the right thing (though that has getting better, though that might be just my growing experience on how to find things), but they put real, actual effort into documentation.
Also, Microsoft has a very strong "corporate style guide" for API design. Every MS API within their major silos is built exactly the same way as every other API. Once you've had some experience with them, it's easy to figure out the others. I find Android to be down-right schizophrenic in comparison.
It's one of the many reasons I continue to focus on MS platforms for my work. It's been 20 years since they were the hostile "kill everything that moves" company that people lament.
hire entire teams whose only jobs were to write documentation
In contrast, I've always found Microsoft's documentation to be incredible.
I don't know how Apple and Google work, but as a long-time-ago MSFT employee, I can tell you it is because they have entire teams. Chain-of-command, senior-level, leads, managers (don't know if there's such a thing as User Ed VP/Director, though) the whole works, like Microsoft kinda took it seriously or something. Hence my ranking of docs:
1. Microsoft: could be better, but you're going to have an easy time finding worse. No, they're actually pretty damned good. When I worked there, for instance, there was a big push that example code will be secure. The mantra was "sample code becomes production code". APIs have close-to-real-world examples of usage. "Could be better"? Eh, I don't know what I'd improve, frankly.
2. Back before they got really big, I'd say about Apple's docs, "does the job; it's not Microsoft-quality, but they don't have Microsoft resources, now do they?" Umm, that's not true anymore, and I think the quality has gone down since.
3. Google: just use Stack Overflow. The docs are just going to frustrate you with their incompleteness and outdateness.
I winder how much of Microsoft's focus on documentation and having full teams to produce it was also spurred by the nature of their enterprise business and the whose ecosystem of certification and training it supported (which in turn supported Microsoft in a cyclical nature). Microsoft has a whole set of of official test prep and training material, certified trainers, etc.
Even if the documentation department never made a profit themselves, I imagine being able to point to some revenue and it being an important part of the overall business strategy kept it as feeling fairly important to most execs.
In that Microsoft has it, Google doesn't, and Apple... magic?
But if you're going to run a competent support org, you need to have high-quality, easily-accessible documentation. Because you're not going to know anything about {insert random thing support ticket is asking about}.
And if you've already created those docs for internal use, why not simply make them public?
I can fully believe MS had entire documentation teams, but looking at their newer docs, and much of what they've done with the old ones, it seems like those teams have mostly disappeared.
MS has been great with documentation, but sadly in the recent years they've also been "outsourcing" a lot of the work to GitHub and relying on "community" to fix everything they broke in the horrid MSDN->docs migration. I use their docs daily, and I regularly come across stuff like this:
I've also noticed a relatively huge amount of grammar/spelling errors in their newer docs, no doubt because MS has lost much of its real documentation team.
Fortunately most of my work with Win32 uses stable APIs that have been around since Win95/NT4, and thus are nicely documented in the infamous WIN32.HLP.
Even so the Symbian team did some pretty cool things such as creating open source documentation standards for C++ and the tools to support that.
Source: I was there.