Hacker News Reader

Comment by gambiting | Hacker News Reader

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.

View on HN

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

Reply on news.ycombinator.com