Hacker News Reader

Comment by defaultname | Hacker News Reader

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.

View on HN

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.

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.

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.

Haha, yes, direct emails for folks in xbox is very useful, the xfest advice is very solid.

I actually went from working at a first party studio inside Microsoft to an indie company, so luckily I have my network to fall back on. Now I just need to work out how to do the same for Sony and Nintendo...

There _used_ to be a Japanese game developers mixer at GDC (not sure if it's still around) - I met some folks from Nintendo there, though nobody specifically on the hardware side. Worth a shot, though. :)

Right. And this would be so easy to fix too.

  a) crawl your own documentation and find dead links.
  b) monitor 404 errors and track down the source (via referer headers, etc.).
  c) ask the user on the 404 page what they were hoping for or provide a search menu, record it, and have someone manually review.
  d) add a redirect management engine, so you can redirect links that you can't/won't ever fix.

I'll write a crawler and get this done for CGA docs (Compute, Graphics and AI).

Thanks for the tip.

Sarcastic? I can't tell.

I didn't mean to imply it was trivial, but the concept of crawling your own documentation is quite sound and should just be part of good document maintenance.

There are some plenty good crawlers already. I'm guessing one of them has a 404 report that could hopefully be used to find dead links.

not sarcastic, and yes I'll probably use a crawler library :)

Cheers! Good luck to you.

I agree with both of you -- Microsoft documentation is generally excellent and extremely detailed and often more than just what you'd get from automatically generating it from code comments.

But the tools constantly send you to links that don't work or provide no useful information. It's a very weird disconnect. I never trust the "click here to open documentation page".

Half right....

The link rot in MS documentation pages is simply maddening. If it’s not a 404, it’s completely different content that is only relevant to v.latest.

Just the other day I was trying to look up a behavior specific to an older version of Windows and the content was completely replaced with content only relevant to Windows 10 (and there was no real parity here to what I needed). I had to go to archive.org to find the information I was looking for from that page.

When I can actually find the docs I need, they are usually great but all too often just finding that content is frustratingly difficult.

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

> 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.

"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.

> 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.

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.

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.

The last sentence is a real gem. Zero trolling / Real question: What do you miss about CHM? My guess: It's a single package you can easily share and doesn't break once deployed (like a live website). :)

It was also fast, used quite minimal amount of resources even when there was a lot of diagrams included. Did I mention fast? Sure, generating an index could take a while - on PIO3/PIO4 drive with 486.

N.B. The first time I've read Time Management for System Administrators, it was CHM file I just copied onto my free (won in competition) Windows Mobile PDA.

Nope. They've always had a lot of documentation. It's often been crap. I've been developing for MS platforms off and on since Win3.1, and have constantly dealt with cycles of "knowing API function A requires you understand what an X is, linked to function B, which only discusses X in terms of function A.". They write a lot, but it's not good. It's like a Hollywood western set where your at just the fronts of buildings. Lots of them, no depth.

You always have to get a 3rd party book to figure this crap out... if you can find one. And if you're off and on, then you're constantly playing this game every few years.

Frankly the X11 books out of O'Reilly are my standard for "good."

I don't agree with this at all. I spent a solid decade doing predominantly Windows development and I haven't felt the need to buy a book on any Microsoft topic since, like - "learn Visual Basic 5". While they probably had a good stretch of years from like after VS2008 until maybe after VS2015 where the documentation was clearly not a focus, I've never had any trouble learning first-and-foremost from the documentation and have often used MSDN as a good example of not needing to already understand the entire topic to benefit from first-party documentation on that topic.

> This kind of snotty reply is always interesting

It’s a typical HN Apple Zealot tactic. They simply lie to boost their cult.

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.

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.

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...

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.

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

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.

>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.

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

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.

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.

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.

Reply on news.ycombinator.com