5 ms·

Microsoft, for all their warts, has the absolute best documentation for every public API in Windows. I'd go so far as to say it's better on average than manpage

by duped 1y ago

Microsoft, for all their warts, has the absolute best documentation for every public API in Windows. I'd go so far as to say it's better on average than manpages in Linux and BSD and light years better than the actively hostile bullshit from Apple. Submitting a bug report though, you gotta know people or know where to ask.

viraptor 1y ago
It really depends how far you go. The basics - they're pretty good. But for the more complicated things they just ignore all context and pretty much restate the names of functions/arguments without explaining how/why things work. See for example https://learn.microsoft.com/en-us/windows/win32/api/tsvirtualchannels/nn-tsvirtualchannels-iwtsbitmaprenderer https://learn.microsoft.com/en-us/windows/win32/api/tsvirtua... and https://learn.microsoft.com/en-us/windows/win32/api/tsvirtualchannels/nn-tsvirtualchannels-iwtsbitmaprenderer https://learn.microsoft.com/en-us/windows/win32/api/tsvirtua... What does the terminal services renderer do? "It renders bitmaps you dummy, just look at those arguments!"
- pimeys 1y ago
  Some of the advanced stuff has great docs. E.g. SQL Server and its wire protocol. When you need to write client to a language that doesn't have one, the TDS doc from Microsoft is amazing. Compare that to e.g. Oracle and you know what I mean. In general SQL Server is such a great product. If you cannot choose PostgreSQL for some reason, make sure your buying manager plays golf with the Microsoft sales people, not with Oracle.
userbinator 1y ago
The old documentation was the best. The new stuff is a mix of barely acceptable and absolute crap, and some of it is even AI-generated. Here's a recent funny: https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/transfer-data-to-isochronous-endpoints https://learn.microsoft.com/en-us/windows-hardware/drivers/u... "The characteristics of the endpoint determine the size of each packet is fixed and determined by the characteristics of the endpoint."
dspillett 1y ago
> Microsoft, for all their warts, has the absolute best documentation for every public API in Windows. That is true in some areas of MS's output, but far from all. Some of their documentation is concise but understandable, complete, and up-to-date. Some of it is auto-generated garbage that is only of use if you already know what you are doing and looking for a remainder of a detail. Some of it is absolutely awful, I've run into numerous issues with Azure related documentation. This is in part because that side of things is rapidly evolving, but sometimes the new information isn't even there, and sometimes it is faff to identify it from information about the previous couple of iterations that are now deprecated. One recent example: installing some of their SQL Server and Azure storage access tooling on the latest Ubuntu LTS release (24.04, now over a year old). The repos are there, maintained, and supported, but the documentation doesn't mention anything beyond 22.04. Yes it is easy to work out what to change, mostly just substitute 24.04 for 22.04, but the docs should be updated. Also, instructions from different documents, all from MS, put their public keys for package signing in different places, which can cause confusion (not an issue for someone like me familiar with apt & related tooling, but I can imagine it being very frustrating to someone less experienced with those parts).
- duped 1y ago
  That's why I said "windows" and not "microsoft." Azure is a dumpster fire.
xigoi 1y ago
This is peak documentation: https://learn.microsoft.com/en-us/dotnet/api/microsoft.office.core.msotristate?view=office-pia https://learn.microsoft.com/en-us/dotnet/api/microsoft.offic...

by duped 1y ago

viraptor 1y ago

It really depends how far you go. The basics - they're pretty good. But for the more complicated things they just ignore all context and pretty much restate the names of functions/arguments without explaining how/why things work. See for example https://learn.microsoft.com/en-us/windows/win32/api/tsvirtualchannels/nn-tsvirtualchannels-iwtsbitmaprenderer https://learn.microsoft.com/en-us/windows/win32/api/tsvirtua... and https://learn.microsoft.com/en-us/windows/win32/api/tsvirtualchannels/nn-tsvirtualchannels-iwtsbitmaprenderer https://learn.microsoft.com/en-us/windows/win32/api/tsvirtua... What does the terminal services renderer do? "It renders bitmaps you dummy, just look at those arguments!"

pimeys 1y ago
Some of the advanced stuff has great docs. E.g. SQL Server and its wire protocol. When you need to write client to a language that doesn't have one, the TDS doc from Microsoft is amazing. Compare that to e.g. Oracle and you know what I mean. In general SQL Server is such a great product. If you cannot choose PostgreSQL for some reason, make sure your buying manager plays golf with the Microsoft sales people, not with Oracle.

userbinator 1y ago

The old documentation was the best. The new stuff is a mix of barely acceptable and absolute crap, and some of it is even AI-generated. Here's a recent funny: https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/transfer-data-to-isochronous-endpoints https://learn.microsoft.com/en-us/windows-hardware/drivers/u... "The characteristics of the endpoint determine the size of each packet is fixed and determined by the characteristics of the endpoint."

dspillett 1y ago

> Microsoft, for all their warts, has the absolute best documentation for every public API in Windows. That is true in some areas of MS's output, but far from all. Some of their documentation is concise but understandable, complete, and up-to-date. Some of it is auto-generated garbage that is only of use if you already know what you are doing and looking for a remainder of a detail. Some of it is absolutely awful, I've run into numerous issues with Azure related documentation. This is in part because that side of things is rapidly evolving, but sometimes the new information isn't even there, and sometimes it is faff to identify it from information about the previous couple of iterations that are now deprecated. One recent example: installing some of their SQL Server and Azure storage access tooling on the latest Ubuntu LTS release (24.04, now over a year old). The repos are there, maintained, and supported, but the documentation doesn't mention anything beyond 22.04. Yes it is easy to work out what to change, mostly just substitute 24.04 for 22.04, but the docs should be updated. Also, instructions from different documents, all from MS, put their public keys for package signing in different places, which can cause confusion (not an issue for someone like me familiar with apt & related tooling, but I can imagine it being very frustrating to someone less experienced with those parts).

duped 1y ago
That's why I said "windows" and not "microsoft." Azure is a dumpster fire.

xigoi 1y ago

This is peak documentation: https://learn.microsoft.com/en-us/dotnet/api/microsoft.office.core.msotristate?view=office-pia https://learn.microsoft.com/en-us/dotnet/api/microsoft.offic...