12 ms·

> 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

> 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.
- throwaway894345 5y ago
  > This kind of snotty reply is always interesting. I've been a professional developer for 25 years. I didn't interpret it as "snotty" (not beyond the norm for this forum, anyway). Could have been worded better, but charitable interpretation is an HN guideline. > 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. Or perhaps the parent just disagrees with you on merit and there is no nefarious underlying motive? In my experience at least, Microsoft's ethos and behavior has improved significantly in the last ~decade with respect to openness, developer friendliness, attitude toward open source, product quality, etc. It seems clear to me that there is some broad cultural change at MS and it seems plausible that it could affect documentation quality as well. Personally, I don't have a dog in this documentation fight, but your comment seems unjustifiably angry.
  - defaultname 5y ago
    It isn't that it's nefarious but rather that people who adopted Microsoft late rationalize that the company has a maligned history (some deserved, some not) by declaring that everything is different now. This appears in conversation after conversation where some current Microsoft enthusiast declares that everything was crap, but now it's wonderful. But a lot of things were already very good to excellent. I mean, one of the things you mentioned was developer friendliness yet the company has forever had industry leading developer relations. They've always had great documentation (there are going to be some developers who will still struggle and fail, but that isn't the fault of the documentation which can only drag them so far). SQL Server has been a great product for literally decades. NT was actually a great OS for the era and vis-a-vis its contemporaries. Microsoft has always been very "open" in fields where they are struggling. And on and on. They did a lot of great things in the past along with bad things. And right now they're doing great things along with bad things. Every org is a mixed bag.
- p_l 5y ago
  arguably it's been the last decade that documentation from MS suffered, specifically around the time that their software stopped shipping with CHM&co files and started opening web pages. But they are quite actively rebuilding from the switchover. I still miss CHM.
thrower123 5y ago
That documentation exists at all has been enough to put MSDN at the top for the past couple decades. Win32 doc has always been good, back into the 90s. Some of the Sharepoint and Lync and when they were starting to open source all the things has been lacking. There was also that stretch where they axed all the QA department... Shudder...

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.

throwaway894345 5y ago
> This kind of snotty reply is always interesting. I've been a professional developer for 25 years. I didn't interpret it as "snotty" (not beyond the norm for this forum, anyway). Could have been worded better, but charitable interpretation is an HN guideline. > 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. Or perhaps the parent just disagrees with you on merit and there is no nefarious underlying motive? In my experience at least, Microsoft's ethos and behavior has improved significantly in the last ~decade with respect to openness, developer friendliness, attitude toward open source, product quality, etc. It seems clear to me that there is some broad cultural change at MS and it seems plausible that it could affect documentation quality as well. Personally, I don't have a dog in this documentation fight, but your comment seems unjustifiably angry.
- defaultname 5y ago
  It isn't that it's nefarious but rather that people who adopted Microsoft late rationalize that the company has a maligned history (some deserved, some not) by declaring that everything is different now. This appears in conversation after conversation where some current Microsoft enthusiast declares that everything was crap, but now it's wonderful. But a lot of things were already very good to excellent. I mean, one of the things you mentioned was developer friendliness yet the company has forever had industry leading developer relations. They've always had great documentation (there are going to be some developers who will still struggle and fail, but that isn't the fault of the documentation which can only drag them so far). SQL Server has been a great product for literally decades. NT was actually a great OS for the era and vis-a-vis its contemporaries. Microsoft has always been very "open" in fields where they are struggling. And on and on. They did a lot of great things in the past along with bad things. And right now they're doing great things along with bad things. Every org is a mixed bag.
p_l 5y ago
arguably it's been the last decade that documentation from MS suffered, specifically around the time that their software stopped shipping with CHM&co files and started opening web pages. But they are quite actively rebuilding from the switchover. I still miss CHM.

thrower123 5y ago

That documentation exists at all has been enough to put MSDN at the top for the past couple decades. Win32 doc has always been good, back into the 90s. Some of the Sharepoint and Lync and when they were starting to open source all the things has been lacking. There was also that stretch where they axed all the QA department... Shudder...