Apple Developer Documentation Is Missing • Hacker News Board

Re: Apple Developer Documentation Is Missing

#51

Post by _jal » Mon, Oct 28, 2019, 2:20 PM UTC

sillysaurusx wrote: post #13

chooseaname wrote: post #9

> Apple, if you want developers to love your platform — and you should, because good developers are your lifeblood — and if you don’t want them to flee for other platforms — and you should be worried about that, because the web is everywhere and Microsoft is coming for you — then you need to take this seriously. Adopt the mentality that has served other frameworks and languages so well: If it isn’t documented, it isn…

Look, this is just going to fall on deaf ears. Apple isn't listening. Their machine is output only. That's not really true. Apple is active on Twitter and actively reaches out to correct problems. For example, when I complained that their Xcode beta hangs when you open a large file, an Xcode dev reached out to me and asked for a repro case. https://twitter.com/theshawwn/status/1175197286349119490 (I'm not an Apple fa…

Taking bug reports on Twitter is nice, but not comparable to improving documentation.

One is a developer reaching out (costs: developer time, management involvement: granting permission). The other is a change in project plans, staffing, workflow and timelines (costs: large, management involvement: massive).

Re: Apple Developer Documentation Is Missing

#52

Post by dnautics » Mon, Oct 28, 2019, 2:21 PM UTC

52-6F-62 wrote: post #46

AlexandrB wrote: post #37

Earlier quoted context omitted.

Isn't that the exception that proves the rule though? Why is Twitter the most effective way to get developer support from Apple as opposed to their own website?

Yeah. As much as I appreciate their responsiveness on Twitter, it doesn't much help those of us who are not on Twitter. (Tangential rant: I dislike how it seems like the most effective path for anything resembling customer service from many companies is to call them out on Twitter alone. I've written emails to some companies over months to no single response—but to look on their Twitter you'll see an answer within ho…

That shouldn't be surprising as Twitter is a public forum, so there's more accountability.

Re: Apple Developer Documentation Is Missing

#53

Post by AlanYx » Mon, Oct 28, 2019, 2:22 PM UTC

cyberferret wrote: post #40

Still? It has been a while since I have done any Apple platform specific native development, but I remember about 5 or 6 years ago writing an iOS and OS X app for communicating with an audio modelling device, and the documentation for CoreMIDI was woefully lacking. I couldn't believe that a part of the Apple operating systems that had been ingrained for years had so little documentation and examples at that time. I e…

>I haven't checked, but are things like the MIDI framework still badly documented in the Swift docs?

Documentation for the entire audio stack has actually gotten quite a bit worse. Many references have been removed without new replacements being provided. In many cases, there are broken links in what little documentation remains. (For example, TN2274, which describes the USB audio stack is still around, but several of the outgoing links, for example the documentation for developing a USB audio plugin, are now broken, with the sample code deprecated and removed with no replacement.) New frameworks like AVAudioEngine simply don't document important limitations, particularly for OS X.

The Core Audio mailing list used to be a good place to get help and answers in cases where the documentation is weak, but traffic has withered and no from Apple seems to reply to messages any more. There has been a total of only four messages on the mailing list this month.

It's really a shame, because the audio stack is well-designed, but the documentation is so poor except for the basics that newcomers would have difficulty getting anything tricky off the ground.

Re: Apple Developer Documentation Is Missing

#54

Post by buckminster » Mon, Oct 28, 2019, 2:22 PM UTC

macinjosh wrote: post #8

ebg13 wrote: post #6

Earlier quoted context omitted.

> Calling out other people's work as 'garbage' is pretty shameful Apple is not a people. Apple is a TRILLION dollar megacorp. They can afford more.

Yeah... but you do know that Apple is comprised of actual real people like you and me though, right?

A partnership is made of people. A limited liability corporation is not. Sure, it employs people, as do I, but I am not made of my employees and neither is Apple.

Re: Apple Developer Documentation Is Missing

#55

Post by czr » Mon, Oct 28, 2019, 2:23 PM UTC

Amorymeltzer wrote: post #3

Last week's ATP[1] had a segment on this, in particular a discussion of https://nooverviewavailable.com/ which has an estimated breakdown of what percent of each framework has documentation. 1: https://atp.fm/episodes/349

timestamped link: https://overcast.fm/+R7DXB8Hbs/14:08

Re: Apple Developer Documentation Is Missing

#56

Post by nullandvoid » Mon, Oct 28, 2019, 2:23 PM UTC

craydandy wrote: post #42

WrtCdEvrydy wrote: post #28

Earlier quoted context omitted.

It's really funny to think about cyclical stuff and see how Blackberry used to treat their developers like shit (with stupid signing keys and stuff) and just look at Apple falling into the same trap.

And this reminds me of the documentation quality of Symbian around 2005-2007. I would highly recommend the author of the article the check it out, before lamenting Apple's documentation.

I mean it's a discounted OS is it really a comparison?

We're talking about one of the biggest platforms in the world here with unlimited money to throw at this problem there is no excuse

Re: Apple Developer Documentation Is Missing

#57

Post by chriskrycho » Mon, Oct 28, 2019, 2:26 PM UTC

epalm wrote: post #7

macinjosh wrote: post #4

I am sure all the documentation this guy has ever written has been 100% perfect. /s Calling out other people's work as 'garbage' is pretty shameful. In my experience Apple's documentation is some of the best around. They have sample projects showing you how APIs work, good integration into their IDE, and lots of talks on video about their APIs given by the very engineers that built the thing. Not even to mention thei…

One doesn't need to write perfect documentation to point out bad documentation. That said, I was hoping for more concrete examples.

This comment was one of the ones that led me to update the title of the post. My intent: "Having this much missing is garbage." How people took it: "What exists is bad." Thus, the rewording to "Missing."

Re: Apple Developer Documentation Is Missing

#58

Post by tonynguyen1 » Mon, Oct 28, 2019, 2:27 PM UTC

AlanYx wrote: post #53

cyberferret wrote: post #40

Still? It has been a while since I have done any Apple platform specific native development, but I remember about 5 or 6 years ago writing an iOS and OS X app for communicating with an audio modelling device, and the documentation for CoreMIDI was woefully lacking. I couldn't believe that a part of the Apple operating systems that had been ingrained for years had so little documentation and examples at that time. I e…

>I haven't checked, but are things like the MIDI framework still badly documented in the Swift docs? Documentation for the entire audio stack has actually gotten quite a bit worse. Many references have been removed without new replacements being provided. In many cases, there are broken links in what little documentation remains. (For example, TN2274, which describes the USB audio stack is still around, but several o…

This is so true. Audio APis are poorly documented. I have only done my task by customizing examples :).

Re: Apple Developer Documentation Is Missing

#59

Post by _jal » Mon, Oct 28, 2019, 2:27 PM UTC

macinjosh wrote: post #8

ebg13 wrote: post #6

Earlier quoted context omitted.

> Calling out other people's work as 'garbage' is pretty shameful Apple is not a people. Apple is a TRILLION dollar megacorp. They can afford more.

Yeah... but you do know that Apple is comprised of actual real people like you and me though, right?

Sure, and actual real people (even smart, nice, capable, well-meaning ones) sometimes turn out garbage, or don't even try to produce.

Ignoring that out of kindness is silly. Any good professional should welcome honest feedback; if you can't criticize a $T company because it might hurt someone's feelings...

Complaining about the docs is important feedback, aimed at ultimately making Apple healthier. And getting to the point where the docs are sub-par means priorities have shifted over a period of years, and will take that long to get back in shape. That's not on any one person, not even Cook, except in the ultimate responsibility sense.

Re: Apple Developer Documentation Is Missing

#60

Post by balls187 » Mon, Oct 28, 2019, 2:27 PM UTC

My issue with this is that the developer is comparing his experience with Apple's documentation over a few months, with his anecdotal experience over 4 years.

Part of gaining experience with a platform is the ability to source answers to technical questions effectively, including how to use official documentation effectively.