4 ms·

I don't have a view on SDK documentation but the best API documentation I've read is the Win32 docs. Why? They are comprehensive, detailed, consistent, systema

I don't have a view on SDK documentation but the best API documentation I've read is the Win32 docs. Why? They are comprehensive, detailed, consistent, systematically presented, clearly explained and professionally written. Microsoft documentation has sadly gone steeply downhill since.

userbinator 4y ago
I still use Win32.hlp for most of my reference needs. Microsoft documentation has sadly gone steeply downhill since. I heard they decided to get rid of most of their documentation writers, and instead rely on "the community" to do it for them. And this horrible migration to a new system, which was basically an act that only the team doing it seems to be proud of: https://news.ycombinator.com/item?id=11626886 https://news.ycombinator.com/item?id=11626886
- garren 4y ago
  Way downhill. The MSDN circa 1996-2000 (if that's what it was called, I don't recall) was excellent. Their C/C++/Win32 documentation was clear, helpful, and concise. Then with the advent of .Net (or, at least, around that time, say 2000+) things just ballooned and suddenly the MSDN became super difficult to navigate, almost overnight. Even today, there's a lot (a lot) there but it's nowhere near as useful as is used to be. The MSDN habit of providing a TOC to the left of any given article seems like it /should/ be useful, but instead it's been beaten to death. There must be a better way to navigate their documentation than that. Also, surprisingly often links to other documentation are broken - that's not new, it's always been the case iirc, but it's much more prevalent these days. And, some of their stuff has a lot of documentation, but it's just difficult to follow. I swear they're paying technical writers by the number of sections they can chop a give subject into. I was looking into Azure/Business Central documentation a while back and didn't find anything useful even though there's a ton of information there. I had ~10-15 tabs open all roughly referencing different pieces of what I thought I needed. Eventually, I stumbled across a dev blog, not MS, describing almost exactly what I needed, along with some crucial details that I never saw in Microsoft's documentation.
stevenwoo 4y ago
What year? I can remember around 1998? having difficulty with the foreign language IME and having to delve through the disks we got from MSDN or something?(I forgot the name) from our annual subscription to figure out the details of using it and finding out it was only documented with examples in a prior year we did not have and having to dig up the example files someone helpfully archived on their non Microsoft website (it was scrubbed from the Microsoft website for some reason). Then I noticed some other poor developer have the exact same issue (so it wasn't just me!) on usenet so I just emailed the files to him.

userbinator 4y ago

I still use Win32.hlp for most of my reference needs. Microsoft documentation has sadly gone steeply downhill since. I heard they decided to get rid of most of their documentation writers, and instead rely on "the community" to do it for them. And this horrible migration to a new system, which was basically an act that only the team doing it seems to be proud of: https://news.ycombinator.com/item?id=11626886 https://news.ycombinator.com/item?id=11626886

garren 4y ago
Way downhill. The MSDN circa 1996-2000 (if that's what it was called, I don't recall) was excellent. Their C/C++/Win32 documentation was clear, helpful, and concise. Then with the advent of .Net (or, at least, around that time, say 2000+) things just ballooned and suddenly the MSDN became super difficult to navigate, almost overnight. Even today, there's a lot (a lot) there but it's nowhere near as useful as is used to be. The MSDN habit of providing a TOC to the left of any given article seems like it /should/ be useful, but instead it's been beaten to death. There must be a better way to navigate their documentation than that. Also, surprisingly often links to other documentation are broken - that's not new, it's always been the case iirc, but it's much more prevalent these days. And, some of their stuff has a lot of documentation, but it's just difficult to follow. I swear they're paying technical writers by the number of sections they can chop a give subject into. I was looking into Azure/Business Central documentation a while back and didn't find anything useful even though there's a ton of information there. I had ~10-15 tabs open all roughly referencing different pieces of what I thought I needed. Eventually, I stumbled across a dev blog, not MS, describing almost exactly what I needed, along with some crucial details that I never saw in Microsoft's documentation.

stevenwoo 4y ago

What year? I can remember around 1998? having difficulty with the foreign language IME and having to delve through the disks we got from MSDN or something?(I forgot the name) from our annual subscription to figure out the details of using it and finding out it was only documented with examples in a prior year we did not have and having to dig up the example files someone helpfully archived on their non Microsoft website (it was scrubbed from the Microsoft website for some reason). Then I noticed some other poor developer have the exact same issue (so it wasn't just me!) on usenet so I just emailed the files to him.