8 ms·
Maybe I’m a bit of an outlier, or maybe personally outdated, but I find Apple’s documentation to be generally good, albeit requiring patience. Apple’s document
by arthurofbabylon 3y ago
Maybe I’m a bit of an outlier, or maybe personally outdated, but I find Apple’s documentation to be generally good, albeit requiring patience.
Apple’s documentation offers neither examples nor answers to common questions (features of stellar documentation), however it works well with a first principles, read-it-twice mentality. The key info is there, just not emphasized.
For those who read the documentation twice and feel comfortable organizing the architecture without guidance, the documentation is highly workable.
I wonder if folks more grounded in web development favor a quicker, architecture-agnostic, copy/paste, just-work-out-the-box style of documentation. (When I’m working on the web, I do!) But Apple’s platforms are native, their frameworks build upon native infrastructure, and so they require consideration of the fundamentals and underlying systems, features that preclude just-give-me-the-snippet development.
(That’s my take, with my own biases. I don’t mean to contradict or put down any other perspectives. I am certain that in many ways, including many of which I am unaware, I am naive.)
- redandblack 3y agoAdditionally imho, Apple does a fantastic job in "naming" things, everywhere in their ecosystem - including their SDK
- jwells89 3y agoThe overly descriptive names get made fun of online, but they’re frequently self-explanatory enough that they can be pulled from autocomplete, skipping the documentation entirely.
- fingerlocks 3y agoYeah I’m with you. I don’t understand what everyone is complaining about. There’s a few things that are undocumented here and there (IOSurfaceRef) but you can sniff out how it works with a little trial and error. I often code offline with only the Apple docs as reference, not a problem.
- eviks 3y agoHow much trial and error to sniff out 80%? "Core Audio 124 / 618 (20.1%"
- eviks 3y agoExcept that "examples" and "answers to common questions" are at the top of the "first principles" when it comes to documentation, so yeah, if you ignore key quality metrics, quality improves
- arthurofbabylon 3y agoWhat do you mean by “first principles”? Do you mean top-ranking criteria? Or do you mean axiomatic?