Good documentation is one of those things whose presence is felt only when it’s absent
On Apple's Piss-Poor Documentation
51–60 of 348 posts
Re: On Apple's Piss-Poor Documentation
#52Earlier quoted context omitted.
I'm curious who maintains the Android docs. Is it all open source? Is any of Apples?
Based on the Android source code I've seen while working on Android projects, I think a good portion of the Android docs are generated by the inline documentation from the Android open-source project. But on top of that, Google also produces high-quality long-form guides. Those are first-party guides, found at https://developer.android.com/ . (Google maintains the Android developer site.)
Ah ok, thanks for the response! I've seen a lot of value in automatically generated docs from inline code. Perhaps that's a key baseline strategy for improvement.
Add then padding that with the long-form guides with concepts and examples.
Re: On Apple's Piss-Poor Documentation
#53Has anyone else noticed that Apple has been slowly moving away from the long-form guides that were helpful at explaining core concepts? I remember once seeing a comprehensive guide on code signing, but over the years it appears to have been scrubbed from their documentation resources. In its place is a much less helpful (but prettier-looking) guide. In comparison, I've noticed Android has FANTASTIC developer document…
Yes! Apple used to have Technical Notes that were a deep dive into how the OS is implemented. They were super helpful in troubleshooting and optimizing for Mac OS. They haven't published anything like this in over a decade.
I suspect someone took "hiding implementation details" too seriously, and now Apple never talks about how anything works (it's all magic). You only get function's signature, and "documentation" that is basically just the function name with added spaces between words.
Re: On Apple's Piss-Poor Documentation
#54I have been trying to optimize a initContainer written in NodeJS and one of the experiment I am trying out is to rewrite it in .NET Core and Microsoft's documentation has been pretty good - it is clear, well organized, gives you examples for each API and there are how-tos for things that people typically care about - the architecture docs linked from here for e.g. https://docs.microsoft.com/en-us/dotnet/ API docs exa…
Microsoft has put lots of effort into their docs in the past couple years, and it's pretty great. Under the "Version" dropdown you can flip to see the same docs in a specific version or platform (Framework vs Core), and this is pretty helpful for porting/upgrading code, as well as coming from a Google search or Stack Overflow link -- you can easily get to the docs for the version you're working with. The other great…
Personally I keep a .NET decompiler on my taskbar. I was about to say I like being able to find all references and usages of internal variables, but I see now the site does a pretty good job. I also like directly seeing how my code utilizes the library functions (not just the .NET libraries, sometimes nuget packages too). The decompiler also removes ambiguity of "what code is actually being ran". ILSpy has worked nicely for me, it has the extra perk of having nice integration with LINQPad (another must-have for .NET developers)
Re: On Apple's Piss-Poor Documentation
#55An anecdote I heard from a colleague:
He was trying to find out whether it's safe to call a particular iOS API function off the main thread. Obviously, the docs didn't say. He googled a bit and found a support forum where someone had asked. An Apple engineer responded: "I don't know, but I'm looking at the code, and there sure are a lot of locks!"
Re: On Apple's Piss-Poor Documentation
#56The particularly sad cases are when The Great API Renaming took things with older names that had good documentation and failed to copy the documentation to the new ones! Deprecations usually don’t indicate their preferred replacements either. As has been the case for years, docs may exist if you know where to look.
As for SwiftUI (documentation aside) it is very powerful, even with its current API holes, and the benefits are huge. You do have to slightly rethink how you might approach certain things but ultimately SwiftUI produces shorter and cleaner code with no XIBs. (Hint: If you do end up with pages of hacky work-around code, you’re doing it wrong and should stop.) I have no doubt it will be the primary/preferred mechanism in 1-2 years.
Re: On Apple's Piss-Poor Documentation
#57Has anyone else noticed that Apple has been slowly moving away from the long-form guides that were helpful at explaining core concepts? I remember once seeing a comprehensive guide on code signing, but over the years it appears to have been scrubbed from their documentation resources. In its place is a much less helpful (but prettier-looking) guide. In comparison, I've noticed Android has FANTASTIC developer document…
Yes, and this is a really shame. Several years ago I was able to become an iOS developer almost completely by reading through Apple's docs and then building a couple of projects on my own. I had a checklist of the programming guides to work my way through from Objective-C, to App Programming, to view controllers, and on. Over the years I found it more and more frustrating to truly understand new frameworks as the documentation changed. iOS development is now a small portion of my job and the lack of good resources is making it hard to stay up to date.
Re: On Apple's Piss-Poor Documentation
#58hjhjghjvjhv
Re: On Apple's Piss-Poor Documentation
#59Here's a contrarian view of this (deplorable) situation, from someone who developed for Microsoft platforms for years. The low quality of the documentation has two reasons: * Protectionism: The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts. * Low commitment: The publisher…
> The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts.
Why in the world would Apple want to ensure a shortage of competent developers — for apps on Apple's platforms! — or protect third party experts?
Re: On Apple's Piss-Poor Documentation
#60I have been trying to optimize a initContainer written in NodeJS and one of the experiment I am trying out is to rewrite it in .NET Core and Microsoft's documentation has been pretty good - it is clear, well organized, gives you examples for each API and there are how-tos for things that people typically care about - the architecture docs linked from here for e.g. https://docs.microsoft.com/en-us/dotnet/ API docs exa…
Microsoft has put lots of effort into their docs in the past couple years, and it's pretty great. Under the "Version" dropdown you can flip to see the same docs in a specific version or platform (Framework vs Core), and this is pretty helpful for porting/upgrading code, as well as coming from a Google search or Stack Overflow link -- you can easily get to the docs for the version you're working with. The other great…
Is there an offline version of that documentation? One of the best things about Java is that you can install the documentation package (depending on your distribution, it's something like java-11-openjdk-javadoc) and the source code package (something like java-11-openjdk-src), and have an offline copy of the full documentation which you can open directly in your web browser and IDE.