8 ms·
Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a w
by bob1029 5y ago
Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked.
Here's a high level overview of GC to give you an idea of how thorough these documents are now:
https://docs.microsoft.com/en-us/dotnet/standard/garbage-collection/ https://docs.microsoft.com/en-us/dotnet/standard/garbage-col...
After reading through all of those sections, I will have developed a very strong understanding for how GC works in .NET and how I should strategically approach it for certain types of problems. I would also have clear, specific code examples to follow as appropriate.
The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR for corrections or enhancements. Good luck doing something even remotely like this with Apple.
- traspler 5y agoWhen I had the opportunity to do something with a Hololens (1st Gen) I was a bit hesitant as the subject matter seemed very difficult and I come from a very different background but when I went through the documentation, tutorials and played around with the SDK I was shocked how simple the SDK and how clear the documentation was. Haven't worked with much MS things besides that but it left a very good impression.
- phamilton 5y agoAzure Cloud Patterns is an amazing set of system design documentation. It's not even about Azure, it's just "here's how to design good systems".
- reasonabl_human 5y agoOne of my favorite bundles of docs to peruse through from time to time. I go in with a specific question and end up going down the rabbit hole of learning a ton of other interesting design patterns instead
- defaultname 5y agoMicrosoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Apple seems to have decided that people really want a tiny subset of members to have primary documentation, and then a weird collection of orthogonal things mixed in as equal interest so you can't tell what you're looking at. It really is quite terrible.
- alisonkisk 5y agoDo you really think that's a "philosophy" and not just thoughtless careless underinvestment?
- dcow 5y agoWhat’s the real difference? It’s the same with good testing. Engineers are expected to operate on timelines and meet deadlines that are often not generated by someone who values good testing and thorough documentation. If Apple wanted good documentation they would have to be comfortable with something that was going to take one week now taking two weeks and they’d probably need to include willingness and ability to document as something they select for when hiring. Or they’d have to spin up documentation teams that work alongside feature engineers, or something. In almost every environment I’m been in, people balk when you force them to confront the reality that good quality things take time and effort. So I don't think it’s just a careless “whoops we forgot to tell the engineers to document” type of scenario. I think it is fundamental to the fabric of the company and those that operate it.
- defaultname 5y agoI mean, generating a list of classes and their members, hierarchies and relationships, with basic annotations, is the easiest, most mechanically automated solution possible. Apple's bizarre documentation seems like it would take significantly more work. It truly seems philosophical. Someone there thinks this is a superior solution.
- z77dj3kl 5y agoYeah, I've noticed this too. Most of the time when you look up something gRPC related, the first links are for some of Microsoft's gRPC documentation! gRPC is one of those projects that I'm not sure if Google really wants uptake or if it's just a dump as a means to open source other things they want uptake in (GCP client libraries, tensorflow, etc). The documentation is awful.
- alisonkisk 5y agoIdoubt google care if you use grpc for its own sake, unless adopting it for its own sake helps you migrate your important tech to google-preferred versions.
- meibo 5y ago.NET documentation is incredible, not just for the language but also the APIs. It's such a joy to work with and even complex concepts seem to be explained very thoroughly. It gets a bit uglier once you cross into WINAPI, COM, etc., but Apple's is still not even close to being a match.
- the_only_law 5y ago> It gets a bit uglier once you cross into WINAPI, COM, etc., but Apple's is still not even close to being a match. I feel like .NET documentation has significantly improved. It wasn't that long ago when I had no idea how to find the documentation from the MSDN home page and had to rely on search engines, but outside I agree. Microsoft's documentation gets a bit rough. Most recently, I found the NDIS documentation unbearable, with broken links and links to 5.x versions. Additionally, I was trying to find the documentation on OLE, and google kept leading me to MFC specific stuff, which was not what I was looking for.
- tonyedgecombe 5y agoSome of the older stuff seems to be getting worse. I was searching for information on Active Scripting and it appeared that documents I had used in the past had disappeared. I know nobody is implementing this from scratch but old code needs to be maintained.
- deleted 5y ago[deleted]
- DenverCode 5y agoI am currently a year away from graduating and we haven't touched documentation once - simply commenting lines of code during DS&A. Does anyone have any recommendations for resources to learn or is it simply reading through documentation akin to that Microsoft link and others like Stripe?
- smoldesu 5y agoI despise Microsoft's products for the most part, but I can't lie: their documentation kicks ass. The C++ documentation is some of the nicest around.
- deleted 5y ago[deleted]
- justinclift 5y agoConversely, when looking through the Azure documentation last week for much of their Python SDK libraries... it's a joke. They have _tonnes_ of new-user intro stuff and similar. Super impressive at first look, but once you're past that and need to dig into complicated things it's all undocumented. Even most of the auto-generated pages in their Python SDK function lists are just "Header -> empty space where content should be -> footer". And nothing else. ... and lets not get started on the docs for Microsoft Graph. :/
- GordonS 5y agoI'm a heavy user of Azure, and I have 2 general issues with their docs. Firstly the documentation for the various SDK is often an issue, because it's often behind the latest release of the SDK. For .NET libraries especially, there is just so much churn that they obviously struggle to keep the docs updated. And then secondly, as you say, there just aren't enough examples beyond the most trivial.
- jitix 5y agoEven back in 2019 I was suggesting everybody to read API development design patterns from the Microsoft documentation. It was clean, neutral (not .net focused) and easy to understand. Microsoft under the new management has really turned around and become a “good” tech company (relative to google and Facebook).
- DaiPlusPlus 5y agoThe “Patterns and Practices” stuff on MS’ site was mostly written in the mid-2000s (when SOAP was a thing). A lot of other content came from MSDN Magazine contributing authors, but that’s discontinued now - I’m curious what drives their whitepapers now.
- deathanatos 5y agoHuh, I have a different impression. Take this doc, that I was staring at the other day: https://docs.microsoft.com/en-us/rest/api/containerregistry/manifests/get-list https://docs.microsoft.com/en-us/rest/api/containerregistry/... ; it is for listing manifests in an ACR repo. The "orderby" query parameter is documented as "orderby query parameter". It is secretly an enum; the values are things like "time_asc" and "time_desc". Later, take the response. "lastUpdateTime" is documented as "Last update time". It's documented as a string, which while technically correct (at the JSON level, yes, it is a string, ish), is wrong. It's an RFC 3339 datetime — I think¹ — but it's also wrong because it is — bizarrely — optional. I actually don't know what sets it, and I have no examples of it being set and the docs don't help. I could also refer one to their documentation about the various performance characteristics of various Azure VM types. Some VM types just aren't listed, so if you're curious about those, good luck, I guess? Run them yourself? We've also hit things like various tri-bools. IIRC, whether you're on a paid SKU for AKS is a weird tribool of sorts. The field has two values, represented by three values: "Free" (meaning free), "Paid" (meaning paid) and the field simply not being present at all, meaning the same as "Free". Not only is the chosen representation terrible, that it is this way is undocumented. ¹I don't have a counter example yet, at least…
- amelius 5y agoStrangely, the best documentation I've seen so far has been PHP. The only reason: because developers could comment right below the documentation. It's like having StackOverflow right there, in the documentation page. (Note: I haven't touched PHP since 20 years or so, so not sure if it's still the case).
- HoppyHaus 5y agoIt still is the case, and the documentation itself has improved greatly over time. PHP is one of the few programming languages that I feel can be used using only the official documentation (with the comments, of course)
- kaba0 5y agoEspecially the warnings like this ISO date function is not actually ISO-compatible :D But I did like the comments idea
- aledalgrande 5y agoYeah documentation looks fine and all for the LinkedIn API, until you have to deal with failures because of outdated validations or missing explanations.
- userbinator 5y agoMicrosoft used to be great at documentation. Then the MSDN->docs.microsoft.com "migration" (what for?) destroyed a lot of old links, and mysteriously introduced errors that weren't there before, like this page: https://docs.microsoft.com/en-us/windows/win32/api/wininet/nf-wininet-internetopenurla https://docs.microsoft.com/en-us/windows/win32/api/wininet/n... (Hint: what does the function return? Countless pages of function references got their return types set to "void" for some inexplicable reason. If that isn't incompetence or malice, I don't know what.) The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR for corrections or enhancements. I actually asked about that error before on their GitHub, but they basically said they'll handle each case as it gets raised. No, I'm not going to fix docs that you broke. It looks like MS basically got rid of all their actual documentation writers and are now trying to rely free labour from the "community".
- cxr 5y ago> The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR We had better than that 10+ years ago: actual wikis. We've regressed quite a bit. Even developer.mozilla.org has gone backwards. Had devmo not been a wiki, I'd have never poured so much effort into the JavaScript docs between 2006–2008.
- fomine3 5y agoIt's better because we can earn GitHub Internet Point® by editing, isn't it? Aside from joking, now internet is no longer peaceful enough to keep publicly editable wiki.
- fortran77 5y agoApple documentation has been awful for decades. There’s so much history and insider knowledge you need to write good desktop MacOS applications. And Microsoft documentation has been excellent for decades. Even pre-Internet with MSJ and Microsoft press.
- jiggawatts 5y agoAre you kidding? Seriously, is this a joke? Literally 99% of anything I search for in Microsoft documentation these days lands me in a page where the only additional English text is the function definition with spaces added between the words! Entire APIs are 100% undocumented, at least in this sense. Security-related APIs are totally undocumented. APIs critical to disaster recovery are totally undocumented. I could go on and on. It wasn't always like this! The C# standard library documented used to be fantastic, with multiple pages of text for pretty much every function. Now? It's hot garbage. Let me give you an example. Not a contrived example of some obscure API that nobody cares about, but a "flagship" feature of dotnet core that was heavily advertised recently as a significant step forward in its capabilities: System.IO.Pipelines This is a complex, difficult to use API. How is it documented, you ask? There's a couple of out-of-date videos showing an earlier version that no long matches the current names. There's some announcement blog articles. There's one overview page that almost -- but doesn't quite -- cover enough to write a useful real-world application. The rest of the documentation reads like this: // Gets the MemoryPool<T> to use when allocating memory. public System.Buffers.MemoryPool<byte> Pool { get; } (From: https://docs.microsoft.com/en-us/dotnet/api/system.io.pipelines.streampipereaderoptions.pool?view=dotnet-plat-ext-5.0 https://docs.microsoft.com/en-us/dotnet/api/system.io.pipeli... ) I am enlightened! I understand now. Before that documentation page, I could not figure out that a getter called "Pool" returning "MemoryPool" returns a memory pool to use for memory allocation. But wow, that documentation really cleared things up! I know I'm being more than a bit snarky, but it's deserved. Microsoft's work is not GNU. It's not truly open source. It's not made by volunteers. MSFT is not a charity. In fact, their products in general are very expensive. I pay through the nose for this! I pay through Windows licensing. I pay through Azure hosting costs. I pay through Office 365. What do I get for this money? Function names with spaces added. > The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR for corrections or enhancements. That is the worst thing about Microsoft documentation. They've realised that they no longer need to allocate any budget at all to technical writers, because people like you will happily volunteer your own time to fix something you're already paying for with your actual cash money. Stop. If you're going to volunteer your time, do it for a charity. Write a Wikipedia article or contribute to Linux. Don't use your precious time on this Earth to help the world's second biggest company for no compensation whatsoever!