On Apple's Piss-Poor Documentation • Hacker News Board

Re: On Apple's Piss-Poor Documentation

#241

Post by Coko » Tue, Nov 10, 2020, 10:09 PM UTC

In some cases the documentation just plain wrong. Core data can be confusing, but worse with wrong documentation. I've had an open radar about the merge policy documentation for over 3 years and nothing has happened, even after talking to a core data engineer at WWDC in 2018.

These two should be the same, but see the conflicting description: https://developer.apple.com/documentation/coredata/nsmergepo... (in-memory changes trump) https://developer.apple.com/documentation/coredata/nsmergeby... (external changes trump)

Same here: https://developer.apple.com/documentation/coredata/nsmergepo... (external changes trump) https://developer.apple.com/documentation/coredata/nsmergeby... (in-memory changes trump)

Re: On Apple's Piss-Poor Documentation

#242

Post by keyle » Tue, Nov 10, 2020, 10:15 PM UTC

simonw wrote: post #217

The difference between https://developer.apple.com/documentation/photokit/phphotoli... and its replacement https://developer.apple.com/documentation/photokit/phphotoli... is pretty damning.

Wow, that's a great example. I'm also very frustrated by the pretty html with absolutely no value.

Re: On Apple's Piss-Poor Documentation

#243

Post by jonhendry18 » Tue, Nov 10, 2020, 10:15 PM UTC

egsmi wrote: post #62

pornel wrote: post #53

Earlier quoted context omitted.

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" th…

There are good reasons to hide the implementation details in documentation. The primary being it’s easier to keep the documentation up to date, our primary topic here. Many languages even publish class interfaces but not necessarily implementation details. That said, a couple of example code snippets on using the interface wouldn’t hurt.

The reason to keep implementation details out of the docs is that people will rely on those implementation details, and then when their app breaks, they won't even think of looking at the documentation for updated implementation details. After all they probably have the old version all but memorized, and the app may break in a way that isn't obviously related to the implementation that changed.

Re: On Apple's Piss-Poor Documentation

#244

Post by jonhendry18 » Tue, Nov 10, 2020, 10:17 PM UTC

tmpz22 wrote: post #12

psahgal wrote: post #7

Has 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…

My guess is they’re realized documentation is a huge cost center and even their own technical writers are overburdened by the churn of deprecating APIs and changing best practices. It’s worse then the JavaScript community.

"documentation is a huge cost center"

It's a tiny cost center, in the grand scheme of things. As it is they probably spend less than they spend cleaning the glass at Apple Park.

Re: On Apple's Piss-Poor Documentation

#245

Post by dragonwriter » Tue, Nov 10, 2020, 10:19 PM UTC

tmpz22 wrote: post #12

psahgal wrote: post #7

Has 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…

My guess is they’re realized documentation is a huge cost center and even their own technical writers are overburdened by the churn of deprecating APIs and changing best practices. It’s worse then the JavaScript community.

For API documentation, if you can specify what you intend to build well enough to build it and validate that you have built even approximately what you intended to build, documentation shouldn't be much more work.

Re: On Apple's Piss-Poor Documentation

#246

Post by hownowbrowncow » Tue, Nov 10, 2020, 10:27 PM UTC

Even the videos at the latest WWDC have been really challenging. For example, the videos showing new Document Driven apps in SwiftUI never released their sample code as a lot of developers sought here: https://developer.apple.com/forums/thread/651193. They really just presented a glorified demo and a few slides.

And yet the old approach for Document Driven Apps is completely out of date straight from the banner page here: https://developer.apple.com/document-based-apps/ (https://developer.apple.com/library/archive/samplecode/Shape...). As mentioned in a lot of comments, there's a real desire to build apps natively but held back by bugs and the lack of entry through even sample code.

Re: On Apple's Piss-Poor Documentation

#247

Post by david-cako » Tue, Nov 10, 2020, 10:28 PM UTC

ansonhoyt wrote: post #133

david-cako wrote: post #27

Apple seems like they are willing to double down on SwiftUI/UiKit with Catalyst. It's getting less simple for new APIs/features but at least Apple's docs have straightforward hierarchy, even with two separate languages. Duplicate APIs usually get deprecated, like the old ALAssets photo library API. Try building an app in .NET. There are dozens of different breadcrumbs you can follow on the MS docs for varying version…

For me, a large part of React Native's appeal is the docs giving me a clear path to make stuff and a fairly public development process. Sure it is also an extra layer of trouble, but I prefer the trouble I can engage with (RN) over the risk of being stranded in the unknowable (Apple).

True, and I do like this a lot. There's a great ecosystem, and the examples are usually pretty good.

But it's also just as easy to get stranded with missing features or features that aren't on both Android and iOS. I did a bunch of geolocation and mapping a while back and I had to write my own support for things like heatmaps. This was eventually merged into the react native maps library, but it is something that can happen if you're doing anything slightly exotic.

Re: On Apple's Piss-Poor Documentation

#248

Post by artifact_44 » Tue, Nov 10, 2020, 10:33 PM UTC

psahgal wrote: post #7

Has 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…

https://en.wikipedia.org/wiki/Inside_Macintosh Guess these days are over...

Re: On Apple's Piss-Poor Documentation

#249

Post by Klonoar » Tue, Nov 10, 2020, 10:34 PM UTC

jjice wrote: post #4

I 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.

Weirdly enough, this tends to be where Apple's docs are still good. They fall apart when you try to move on from it towards Swift & co.

Granted, _finding_ the ObjC old docs can be a pain in the ass, but it's possible. I've literally found answers to some of my questions in OS release notes and nowhere else; part of being an AppKit/etc developer winds up being simply knowing how to search.

Another complaint I have: depending on what era of documentation you need, you often have to qualify your searches differently - e.g, OS X vs macOS.

Re: On Apple's Piss-Poor Documentation

#250

Post by jonhendry18 » Tue, Nov 10, 2020, 10:34 PM UTC

kaycebasques wrote: post #16

I've been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don't know Apple's situation but here's my guess: > Is the documentation team too small? (Likely.) Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no m…

"Part of it is that it's really hard to show a causal link between the docs we create and developer success"

Yep, high traffic to a dev doc web page is ambiguous. Is it because it's really good? Is it because it's bad and people keep coming back trying to understand it? Or is the documentation fine but the API being documented is just hard to use?