55 ms·
Microsoft documentation was historically the gold standard for comprehensiveness and quality. If what the other commenter says (e.g. about their Azure docs) is
by bitwize 7y ago
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?
- LandR 7y agoA 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!
- pjc50 7y agoAt 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.
- userbinator 7y agoThe 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.
- Nullabillity 7y agoI 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.) [0]: https://docs.microsoft.com/en-us/dotnet/api/system.datetime?view=netcore-3.1 https://docs.microsoft.com/en-us/dotnet/api/system.datetime?... [1]: https://docs.microsoft.com/en-us/dotnet/api/system.datetime?view=netcore-3.1#constructors https://docs.microsoft.com/en-us/dotnet/api/system.datetime?... [2]: https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.datetime https://docs.python.org/3/library/datetime.html?highlight=da... [3]: https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.dictionary-2?view=netcore-2.0 https://docs.microsoft.com/en-us/dotnet/api/system.collectio... [4]: https://www.scala-lang.org/api/current/scala/collection/immutable/Map.html https://www.scala-lang.org/api/current/scala/collection/immu... [5]: https://doc.rust-lang.org/stable/std/collections/struct.HashMap.html https://doc.rust-lang.org/stable/std/collections/struct.Hash...
- qidydl 7y agoPython'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).
- Nullabillity 7y agoThe 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] [0]: https://github.com/scala/scala/blob/v2.12.10/src/library/scala/collection/immutable/List.scala#L283-L299 https://github.com/scala/scala/blob/v2.12.10/src/library/sca... [1]: https://www.scala-lang.org/api/2.12.10/scala/collection/immutable/List.html#map[B](f:A=%3EB):List[B] https://www.scala-lang.org/api/2.12.10/scala/collection/immu...