Microsoft have best most fascinating documentation in some cases. It can be fantastically detailed, while being completely useless at the same time.
Take their Azure Python API, which is clearly translated directly from C#: There's a number of functions, which according to the documentation takes a string as an input. The thing is that it won't actually take a string, it will take three or four predefined strings. Everything else will yield no result. The only thing Microsoft doesn't care to put in the documentation is which strings are actually valid and what result you can expect from them.
This is slightly unrelated but there was a time when reading the azure docs where you’d be reading a page for version 1.0 but the sidebar would take you to the documentation for version 2.0 and I actually got caught up writing a mismatched integration and it took me forever to figure out why I had done that.
microsoft's documentation for anything other than .NET stuff is absurdly bad.
i was trying to do some work with their crm solution it took me a literal week to find out how to do simple oauth -- mostly because 99% of the documentation only had .NET examples using their own framework!
Microsoft's documentation for .NET is also absurdly bad.
No, I don't want to do a full reload for every overload of a method. Yes, I might want to see where these extension methods are popping up from, out of nowhere.
Microsoft documentation was historically the gold standard for comprehensiveness and quality. If what the other commenter says (e.g. about their Azure docs) is true, I don't know if things have changed or what. Maybe a post-Nadella culture shift?
At one point they "burned the library" and broke a lot of old MSDN urls. It's now common to find dead links to MSDN on old Stackoverflow posts.
The documentation is definitely there, but finding it can be a curse. The search is worse than Google, the site is surprisingly slow for a bunch of static text, and the ability to discover something when you don't know the right search terms is poor because Microsoft name everything in the most generic way possible.
The Microsoft Docs change from MSDN was horrible (and still is). A lot of content got mysteriously mangled for no discernable reason. Their KB articles, which used to be excellent, have mostly been "disappeared" too. You can see a vast difference in quality between the newly-written pages and what was inherited from before. I find spelling and grammar errors often in the newer pages.
A lot of MS documentation now is awful. Azure stuff especially.
Sometimes there is just no usable documentation for certain things at all. I've even seen documentation for certain Azure things where it just directs you to Stack Overflow!
I guess people's expectations might have been lower? MSDN sucks along every axis I can imagine.
The content is bad: Quick, is System.DateTime[0] timezone-aware? The examples also use (the harmful and bug-prone) DateTime.Now 5 times, while DateTime.UtcNow is only mentioned once, as a minor aside.
The structure is bad: Is something part of "Core", "Framework", "Standard", or "Platform Extensions"? It's particularly ridiculous that trying to switch from Core to Platform Extensions while you're viewing a Core class (such as System.DateTime[0]), you'll get kicked over to.. Framework.
The layout is bad: Look at System.DateTime's list of constructors[1]. It takes up a whole screenful to say what Python's datetime.datetime constructor[2] paragraph says in three lines.
The design is bad: Compare the method listing of .NET's IDictionary[3] to Scala's Map[4], or Rust's HashMap[5]. Which one makes the type signatures the easiest to parse? Which one helps you get where you want to the fastest?
(Hint: For me, at least, not the one that insists on making everything a uniform shade of baby blue.)
Python's datetime appears to have one constructor with several optional parameters, whereas .NET's System.DateTime has several separate constructors each taking a different set of parameters. The MSDN documentation is accurate and correct; your critique applies to the underlying code (which is built to be backwards-compatible to .NET 1.0, which I don't think even supported optional arguments).
The signatures that are useful when developing the library might be more complex than the ones that the library consumer would be interested in. This isn't much of an excuse when you also maintain the documentation tools.
For a similar example, Scala's old collections library had a ton of machinery to ensure that `map` and co. would specialize correctly.[0] But the user never sees that, because they added a mechanism called "use cases", that allow you to override the signature shown in the docs with a simpler one.[1]
