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

Re: On Apple's Piss-Poor Documentation

#311

Post by threentaway » Wed, Nov 11, 2020, 5:34 AM 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…

> I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links

And when you do this, DO NOT serve up the feedback form/popup from some advertising domain, otherwise developers with ad lockers (many, if not most) won't even see it.

Re: On Apple's Piss-Poor Documentation

#312

Post by pjmlp » Wed, Nov 11, 2020, 5:53 AM UTC

I also have to agree, now most modern stuff is only mentioned at WWDC, while the older material is only available in the archive, with its replacement being just the "header" file/module listing.

I just keep saving the ones I need, because even the archive eventually deleted, e.g. Objective-C++ docs.

Re: On Apple's Piss-Poor Documentation

#313

Post by JBiserkov » Wed, Nov 11, 2020, 5:53 AM UTC

delfinom wrote: post #138

gumby wrote: post #76

It's really a shame that a scrappy little company like Apple can't afford the resources to produce documentation, even if not for their own apps at least for the developers who write apps that cause their users to buy the hardware. Maybe when they can get themselves established in the market they'll have enough financial resources to invest in this critical area. === I never liked Ballmer, and really never liked the…

Apple at this begrudgingly allows developers on their platform as they slowly make their own apps to capture all the recurring subscription revenue as the logical endgame of its walled garden.

Absolutely! Have you seen this (interactive) article by the New York Times? It's unbelievable.

https://www.nytimes.com/interactive/2019/09/09/technology/ap...

Re: On Apple's Piss-Poor Documentation

#314

Post by jamil7 » Wed, Nov 11, 2020, 7:14 AM UTC

wlesieutre wrote: post #24

ChrisMarshallNY wrote: post #21

Earlier quoted context omitted.

SwiftUI's docs are a nightmare. Here's a pretty damn cool app: https://swiftui-lab.com

Excellent, thanks for this! Most recent post is "Attributed Strings with SwiftUI" which is something I was wondering about. There's plaintext TextEditor view, but for rich text editing the impression I've gotten is to either fall back to something in UIKit or do it in a WebView. Will check this post out tonight, it might not change anything but I'd at least like a better idea where things stand in SwiftUI. Props to A…

For a small app I recently just wrapped SlateJS in a webview and passed json back and forth. Slate is pretty nice but it would be nice to use a native solution.

Re: On Apple's Piss-Poor Documentation

#315

Post by pmontra » Wed, Nov 11, 2020, 7:52 AM UTC

> No matter what, I’ve been banging on this drum for years. I haven’t a clue what the problem is at Apple.

The problem is that they are selling a lot of iPhones despite the quality of the documentation.

If bad documentation would translate into no apps and into low sales then they would write top notch documentation. They made such a huge profit instead, no wonder they don't care about this and other issues.

Re: On Apple's Piss-Poor Documentation

#316

Post by pjmlp » Wed, Nov 11, 2020, 8:17 AM 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…

Only if you happen to follow Android team developers on Medium (it used to be G+) and Twitter.

The documentation has lots of outdated stuff that only gets updated across Medium, StackOverflow, bug tracking comments, twitter posts, /r/androiddev.

Re: On Apple's Piss-Poor Documentation

#317

Post by [deleted] » Wed, Nov 11, 2020, 8:39 AM 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…

[deleted]

Re: On Apple's Piss-Poor Documentation

#318

Post by lmm » Wed, Nov 11, 2020, 8:50 AM UTC

Polylactic_acid wrote: post #309

hutzlibu wrote: post #177

Earlier quoted context omitted.

Current situation is, money is coming in. Stock market still loves apple. So for them it seems fine.

Basically. What are you going to do? Not release your app on apple devices? No, you will do whatever it takes to work it out yourself.

It might even be in their interests to drive away all but the most dedicated developers. After all, they have more apps than they'll ever need, the problem is always quality.

Re: On Apple's Piss-Poor Documentation

#319

Post by chj » Wed, Nov 11, 2020, 9:09 AM UTC

They really should hire the team behind MDN.

Re: On Apple's Piss-Poor Documentation

#320

Post by habosa » Wed, Nov 11, 2020, 10:08 AM UTC

Disclaimer: I work in Developer Relations at Google.

At most large tech companies (Google, Microsoft, etc) the documentation is the responsibility of the Developer Relations team.

Apple has always been an outlier: they never had a Developer Relations team at all. I've recently seen some job postings for DevRel @ Apple, but this is super new.