[moron4hire]

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.

[mikestew]

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.

[kbenson]

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.

[ethbro]

It also likely traces back to support.

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?

[userbinator]

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.

[moron4hire]

Definitely. Good documentation is hard work, a full-time project all on its own. It drives me nuts how many "hackers" think of it as an afterthought.

[userbinator]

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:

https://docs.microsoft.com/en-us/windows/win32/api/winsock/n...

Compare with the MSDN page which is surprisingly still there (if it isn't when you read this, check the Internet Archive):

https://msdn.microsoft.com/en-us/windows/ms741519(v=vs.100)

Or just plain misleading, like this function which definitely returns a value but has "void" in place of the actual type:

https://docs.microsoft.com/en-us/windows/win32/api/wininet/n...

The page on MSDN is correct as usual:

https://msdn.microsoft.com/en-us/windows/aa385098(v=vs.80)

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.