On Apple's Piss-Poor Documentation
caseyliss.com
On Apple's Piss-Poor Documentation
1–10 of 348 posts
Re: On Apple's Piss-Poor Documentation
#2I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!”
Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me.
So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medium posts because something from before WWDC 2020 might no longer be useful. Or maybe it is. How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs.
Re: On Apple's Piss-Poor Documentation
#3I worked at a phone company that was collapsing in market share and one of the things that always stuck out to me was: complex signing process + documentation.
It seems that as you get larger in the phone space, these things are neglected until you lose market share and then they become a priority.
Re: On Apple's Piss-Poor Documentation
#4I had to work on a small MacOS app written in objective C at my last internship. The documentation was horrible. It was basically non-existent. I understand Swift is the primary language now, but wow, there was basically nothing in the online API reference.
Re: On Apple's Piss-Poor Documentation
#5I worked at a phone company that was collapsing in market share and one of the things that always stuck out to me was: complex signing process + documentation. It seems that as you get larger in the phone space, these things are neglected until you lose market share and then they become a priority.
Apple’s signing processes have only gotten less complex from a developer point of view.
But.. this article is completely correct about SwiftUI documentation.
Re: On Apple's Piss-Poor Documentation
#6I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…
I will say that the WWDC sessions are well presented, and are a good place to start. But you can't use a video for quick reference, and you might be missing context from knowing how it worked the previous year to understand what the new enhancements are. Expect to dig into 2019 videos too. SwiftUI being new at least has the benefit that its sessions can't be any more outdated than that (yet). At most you're reconciling two years.
The Landmarks tutorial is also very well done as a starting point. But a tutorial isn't a substitute for documentation.
Re: On Apple's Piss-Poor Documentation
#7Has 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 documentation. I've found full guides for everything. Even esoteric classes that are rarely used have at least a little bit of documentation.
Re: On Apple's Piss-Poor Documentation
#8I disagree with him on header docs.
Header docs are more likely to be kept in sync with the API than whatever they have online.
Re: On Apple's Piss-Poor Documentation
#9I 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 example -https://docs.microsoft.com/en-us/dotnet/api/system.collectio...
I find the Python docs and tutorials good as well. But that's to be expected for mature language/ecosystem like Python.
Good documentation is a lot of work and skill and it's a thankless job for the most part. So it's really amazing when organizations / OSS communities get it right consistently.
Re: On Apple's Piss-Poor Documentation
#10I could have sworn I read a comment on this site a few years ago where someone claimed they had to submit a support ticket in order to grt documentation for some Apple API.