6 ms·

Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, becau

Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Apple seems to have decided that people really want a tiny subset of members to have primary documentation, and then a weird collection of orthogonal things mixed in as equal interest so you can't tell what you're looking at. It really is quite terrible.

alisonkisk 5y ago
Do you really think that's a "philosophy" and not just thoughtless careless underinvestment?
- dcow 5y ago
  What’s the real difference? It’s the same with good testing. Engineers are expected to operate on timelines and meet deadlines that are often not generated by someone who values good testing and thorough documentation. If Apple wanted good documentation they would have to be comfortable with something that was going to take one week now taking two weeks and they’d probably need to include willingness and ability to document as something they select for when hiring. Or they’d have to spin up documentation teams that work alongside feature engineers, or something. In almost every environment I’m been in, people balk when you force them to confront the reality that good quality things take time and effort. So I don't think it’s just a careless “whoops we forgot to tell the engineers to document” type of scenario. I think it is fundamental to the fabric of the company and those that operate it.
- defaultname 5y ago
  I mean, generating a list of classes and their members, hierarchies and relationships, with basic annotations, is the easiest, most mechanically automated solution possible. Apple's bizarre documentation seems like it would take significantly more work. It truly seems philosophical. Someone there thinks this is a superior solution.
gambiting 5y ago
I'm a games developer working on some AAA xbox productions and I don't think I agree. My #1 impression with Microsoft documentation is that you run into a message "error occurred, click here to open documentation page", you click on it, only to be redirected to a 404 page or simply to MSDN's main website. Like, yes, the pages that exist are usually very well written and detailed. But jesus christ, their links even just between MSDN pages are constantly broken, if you find an article older than 12 months you can be 100% certain nothing on the page will work when clicked on. It's like there is a wealth of knowledge there, but whoever is in charge of maintaining MSDN makes a point of redesiging the entire website every year and breaking literally every link in the process.
- ape4 5y ago
  I've seen this. Also the search on the MSDN website is really bad. For some reason it never gets a reasonable result. I use google with site:docs.microsoft.com
- dafelst 5y ago
  Agreed, the Xbox documentation is hot garbage. They expect you to flip flop between the .chm file shipped with the XDK and online, but like you say the links are almost always broken. On the flip side though the private Xbox dev forums are awesome, I find them more useful than the docs. Sony's PS4/PS5 docs also suck and are a giant pain in the ass to get to because they make you allow-list only specific IP addresses (a nightmare during the pandemic), but at least they are all in one place.
  - gambiting 5y ago
    Yeah, xbox forums are very very good, and you usually get a reply directly from someone on the Xbox Development team within few hours. If you ever get a chance to go to XFest(assuming they still continue after the pandemic), it's really worth going - you get to meet people actually working on the hardware and software, collecting some of their emails goes a long way when working on a game ;-) And yes, PS4/PS5 documentation is....lacking. It's all in one place and at least easily searchable but most functions have descriptions 2 sentences long and you have to look in the samples for the actual knowledge of how to call something.
nextweek2 5y ago
> Microsoft has had superb documentation for decades No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation. The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages. To me Qt's documentation was the benchmark, but the latest documentation from Microsoft has really caught up.
- LeSaucy 5y ago
  Qt5 documentation quality has steadily slid down hill. Any new modules they add you essentially have to peruse the source to understand what/how/why it works.
  - sircastor 5y ago
    I had a coworker critical of my position while working with Qt when I complained about poor documentation, saying that if I needed to know how something worked, I should just read the source.
- defaultname 5y ago
  "No, they've had lot's of documentation. That's not the same thing. " This kind of snotty reply is always interesting. I've been a professional developer for 25 years. For most of those years I was deep in the Microsoft platform. C++, Win32 API, DirectX, COM+/DCOM, OLE, automation, C# / .NET. For decades they've had exhaustive narrative documentation that would give huge backgrounders on everything. Architectural "how it fits" documentation with wonderful diagrams, hierarchies, etc. I could easily find anything and jump to specific APIs. Shitloads of examples. They clearly have had a great documentation focus for a long, long time. Something like the MSDN Library was years before its time. Let me repeat, probably with way more experience in saying this, that Microsoft has done documentation well for years, and I seldom felt deprived (aside from occasionally when they do a restructure and search engines/links go to obsolete links). It is specifically in contrast to Microsoft's long excellent documentation that I find Apple's to be a sad joke. There is some bizarre tendency in here for people to pretend that everything Microsoft does well they've only done well for most recent history, as if this is some sort of odd proselytizing and naysayers should realize that everything has changed.
Apocryphon 5y ago
Embarrassingly, it's been said that Xamarin's iOS documentation is better than Apple's own.
bryanrasmussen 5y ago
>Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. I remember somewhere between 2006-2009 they did a reorganization / reimplementation of their online documentation which meant that the menu was always far too long to load and sometimes killed the browser I was on. Whatever point it was at was the point when I stopped using MS technologies as I figured the open source was just as well, and if not as well documented, at least trying to read the documentation seemed a lot safer.
fpoling 5y ago
I year ago I worked on media decoding code both on Mac and Windows. Documentation for media API sucked on both platforms, but it sucked in different ways. Apple quite frequently left important details and it took me few weeks to understand why the decoding code misbehaved in one particular case. With Microsoft I run into this only once and it was straightforward to fix. Note that in both those cases with Apple and Microsoft StackOverflow and similar sites was not helpful and even harmful retrospectively since that gave wrong direction to dig, but this is another story. On the other hand Microsoft documentation was more shallower. If one knows roughly what to do, then things are OK. But by just reading one can not learn how to solve problems. Guides were not helpful, as those were at too high level. Surprisingly with Apple, when they did described API, they gave helpful hints what to do next. Plus API was named more sensibly.
reactspa 5y ago
Just my 0.02: True, Microsoft has always had extensive documentation. However, during the Ballmer era, there was tremendous version confusion. It was no longer clear which version of software a lot of documentation referred to. I've noticed a huge clean-up in this regard after Satya took over. I suspect he got some very competent person to take over all the public-facing documentation, to make it more user-friendly. The result: I am willing to trust Microsoft documentation again.
PostThisTooFast 5y ago
Amen. I learned enough to start off in C++ from a thin white book from Microsoft about the language. Really excellent. Not to mention that the Windows help system was better in the early '90s than the Mac's is today. Help on the Mac is a disgrace, which is why a lot of applications have just started delivering a PDF or doing all Web-based doc (which sucks when you're trying to work offline) instead of bothering with it.

alisonkisk 5y ago

Do you really think that's a "philosophy" and not just thoughtless careless underinvestment?

dcow 5y ago
What’s the real difference? It’s the same with good testing. Engineers are expected to operate on timelines and meet deadlines that are often not generated by someone who values good testing and thorough documentation. If Apple wanted good documentation they would have to be comfortable with something that was going to take one week now taking two weeks and they’d probably need to include willingness and ability to document as something they select for when hiring. Or they’d have to spin up documentation teams that work alongside feature engineers, or something. In almost every environment I’m been in, people balk when you force them to confront the reality that good quality things take time and effort. So I don't think it’s just a careless “whoops we forgot to tell the engineers to document” type of scenario. I think it is fundamental to the fabric of the company and those that operate it.
defaultname 5y ago
I mean, generating a list of classes and their members, hierarchies and relationships, with basic annotations, is the easiest, most mechanically automated solution possible. Apple's bizarre documentation seems like it would take significantly more work. It truly seems philosophical. Someone there thinks this is a superior solution.

gambiting 5y ago

I'm a games developer working on some AAA xbox productions and I don't think I agree. My #1 impression with Microsoft documentation is that you run into a message "error occurred, click here to open documentation page", you click on it, only to be redirected to a 404 page or simply to MSDN's main website. Like, yes, the pages that exist are usually very well written and detailed. But jesus christ, their links even just between MSDN pages are constantly broken, if you find an article older than 12 months you can be 100% certain nothing on the page will work when clicked on. It's like there is a wealth of knowledge there, but whoever is in charge of maintaining MSDN makes a point of redesiging the entire website every year and breaking literally every link in the process.

ape4 5y ago
I've seen this. Also the search on the MSDN website is really bad. For some reason it never gets a reasonable result. I use google with site:docs.microsoft.com
dafelst 5y ago
Agreed, the Xbox documentation is hot garbage. They expect you to flip flop between the .chm file shipped with the XDK and online, but like you say the links are almost always broken. On the flip side though the private Xbox dev forums are awesome, I find them more useful than the docs. Sony's PS4/PS5 docs also suck and are a giant pain in the ass to get to because they make you allow-list only specific IP addresses (a nightmare during the pandemic), but at least they are all in one place.
- gambiting 5y ago
  Yeah, xbox forums are very very good, and you usually get a reply directly from someone on the Xbox Development team within few hours. If you ever get a chance to go to XFest(assuming they still continue after the pandemic), it's really worth going - you get to meet people actually working on the hardware and software, collecting some of their emails goes a long way when working on a game ;-) And yes, PS4/PS5 documentation is....lacking. It's all in one place and at least easily searchable but most functions have descriptions 2 sentences long and you have to look in the samples for the actual knowledge of how to call something.

nextweek2 5y ago

> Microsoft has had superb documentation for decades No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation. The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages. To me Qt's documentation was the benchmark, but the latest documentation from Microsoft has really caught up.

LeSaucy 5y ago
Qt5 documentation quality has steadily slid down hill. Any new modules they add you essentially have to peruse the source to understand what/how/why it works.
- sircastor 5y ago
  I had a coworker critical of my position while working with Qt when I complained about poor documentation, saying that if I needed to know how something worked, I should just read the source.
defaultname 5y ago
"No, they've had lot's of documentation. That's not the same thing. " This kind of snotty reply is always interesting. I've been a professional developer for 25 years. For most of those years I was deep in the Microsoft platform. C++, Win32 API, DirectX, COM+/DCOM, OLE, automation, C# / .NET. For decades they've had exhaustive narrative documentation that would give huge backgrounders on everything. Architectural "how it fits" documentation with wonderful diagrams, hierarchies, etc. I could easily find anything and jump to specific APIs. Shitloads of examples. They clearly have had a great documentation focus for a long, long time. Something like the MSDN Library was years before its time. Let me repeat, probably with way more experience in saying this, that Microsoft has done documentation well for years, and I seldom felt deprived (aside from occasionally when they do a restructure and search engines/links go to obsolete links). It is specifically in contrast to Microsoft's long excellent documentation that I find Apple's to be a sad joke. There is some bizarre tendency in here for people to pretend that everything Microsoft does well they've only done well for most recent history, as if this is some sort of odd proselytizing and naysayers should realize that everything has changed.

Apocryphon 5y ago

Embarrassingly, it's been said that Xamarin's iOS documentation is better than Apple's own.

bryanrasmussen 5y ago

>Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. I remember somewhere between 2006-2009 they did a reorganization / reimplementation of their online documentation which meant that the menu was always far too long to load and sometimes killed the browser I was on. Whatever point it was at was the point when I stopped using MS technologies as I figured the open source was just as well, and if not as well documented, at least trying to read the documentation seemed a lot safer.

fpoling 5y ago

I year ago I worked on media decoding code both on Mac and Windows. Documentation for media API sucked on both platforms, but it sucked in different ways. Apple quite frequently left important details and it took me few weeks to understand why the decoding code misbehaved in one particular case. With Microsoft I run into this only once and it was straightforward to fix. Note that in both those cases with Apple and Microsoft StackOverflow and similar sites was not helpful and even harmful retrospectively since that gave wrong direction to dig, but this is another story. On the other hand Microsoft documentation was more shallower. If one knows roughly what to do, then things are OK. But by just reading one can not learn how to solve problems. Guides were not helpful, as those were at too high level. Surprisingly with Apple, when they did described API, they gave helpful hints what to do next. Plus API was named more sensibly.

reactspa 5y ago

Just my 0.02: True, Microsoft has always had extensive documentation. However, during the Ballmer era, there was tremendous version confusion. It was no longer clear which version of software a lot of documentation referred to. I've noticed a huge clean-up in this regard after Satya took over. I suspect he got some very competent person to take over all the public-facing documentation, to make it more user-friendly. The result: I am willing to trust Microsoft documentation again.

PostThisTooFast 5y ago

Amen. I learned enough to start off in C++ from a thin white book from Microsoft about the language. Really excellent. Not to mention that the Windows help system was better in the early '90s than the Mac's is today. Help on the Mac is a disgrace, which is why a lot of applications have just started delivering a PDF or doing all Web-based doc (which sucks when you're trying to work offline) instead of bothering with it.