Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Apple Developer Documentation Is Missing

v4.chriskrycho.com

Post reply on HN
Print view View original

41–50 of 400 posts

Re: Apple Developer Documentation Is Missing

#41

Post by chriskrycho »

escape_goat wrote: post #30
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…

I'm sure it hasn't been perfect either, but "I write better developer documentation than the large software corporation Apple" wasn't the focus of his complaint. Specifically, he claims: that large portions of the Swift user interface API are entirely undocumented; that he was unable understand the full capabilities and limitations of the package manager through reference to its documentation; that he finds himself f…

This is a fair criticism; I'm updating the title of the post and adding a note about the change in title accordingly.

Re: Apple Developer Documentation Is Missing

#42

Post by craydandy »

WrtCdEvrydy wrote: post #28
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…

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.

Re: Apple Developer Documentation Is Missing

#44

Post by jasonlotito »

macinjosh wrote: post #12
epalm wrote: post #7

Earlier quoted context omitted.

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

> One doesn't need to write perfect documentation to point out bad documentation. Agreed. Calling something 'garbage' and providing no concrete examples isn't really constructive feedback. It is just name calling.

Not the OP, but I'd provide some examples if there were examples to provide. Unfortunately, their documentation is severely lacking in the area I've worked with recently (Apple Sign In on the server end). Basically, it doesn't exist. I can't point to a specific example other than to say it doesn't exist.

And this should be concerning. If Apple wants people to use Apple Sign In, they should do more than mandate its use. They should make it easy to implement, or, at the very least, provide clear documentation.

Instead, I've had to rely on other documentation outside of Apple that all start by sharing their disappointment with Apple's documentation on this subject, and then try to decipher what Apple is doing.

Re: Apple Developer Documentation Is Missing

#46

Post by 52-6F-62 »

AlexandrB wrote: post #37
sillysaurusx wrote: post #13

Earlier quoted context omitted.

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…

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 hours, or minutes.)

Re: Apple Developer Documentation Is Missing

#47

Post by chriskrycho »

DagAgren wrote: post #33
tpush wrote: post #14

Earlier quoted context omitted.

The main point here is that a lot of documentation is straight up missing . Some of the code samples/sample projects also regularly break. I wonder if Apple has any automation around that.

The only two examples he gives for this "a lot" is a completely new framework that was released about a month ago, and a tool that is, honestly, still in development and not part of normal development workflows for Apple platforms.

Two notes:

1. SPM has been out (and officially supported as part of the Swift Project) since Swift 3 came out. You can defend it as being "not part of normal development workflows for Apple platforms" if you like, but it has been officially supported for years. People would rightly call this out in any other language; it's fair to call it out here.

2. My very strongly held opinion, as I noted at the end of the article, is that you can't actually call something "shipped" until you've shipped the docs.

Re: Apple Developer Documentation Is Missing

#48

Post by School-Cotton »

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…

I agree wholeheartedly that it’s garbage. I don’t want to watch videos, I want comprehensive, detailed API documentation.

Here’s one obvious example that comes to mind: how do I turn on the GPS on iOS? This is documented nowhere. The answer is that location requested with an accuracy above 100 meters will use cell towers, below 100 will use WiFi geolocation, and below some other threshold (10 meters? I forget) will use GPS. But that’s nowhere in the docs. They just tell you “use what you need”.

Here’s another one, what is the maximum size of a process’s address space on an iPhone? This one is not documented anywhere, you actually have to read the kernel source code to figure it out!

These are just two examples that popped into my head from ~3 years of iOS work. But they’re the rule, not the exception. Apple documentation tells you how to do basic and standard things the way Apple expects. It doesn’t give actual details of how things work.

Re: Apple Developer Documentation Is Missing

#50

Post by Vomzor »

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…

A lot of Apple documentation is just a list of functions a class has without any explanation whatsoever. Many sample projects are written in older swift versions and don't compile anymore. Xcode 11 can only convert swift 4 to swift 5. A lot of samples are still swift 2 or 3. So you either have to manually fix the errors or install an older xcode version to convert them. Such a waste of time.

And you know it's bad when Microsoft has better Apple docs than Apple has: https://twitter.com/akashivskyy/status/1187790245804367873

Post reply on HN