Apple Developer Documentation Is Missing • Hacker News Board

Re: Apple Developer Documentation Is Missing

#31

Post by mikestew » Mon, Oct 28, 2019, 2:06 PM UTC

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 am sure all the documentation this guy has ever written has been 100% perfect.

I’m a fucking awful violin player, but I know unskilled/professional playing when I hear it. Is the implication that I have no room to complain when I buy a ticket and the performance is bad?

Re: Apple Developer Documentation Is Missing

#32

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

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…

1. As others have noted, the metric in question (and what I do call out in the post) is: does documentation for this even exist?

2. Turns out that yes, I do prioritize documentation extremely highly when I publish projects for other people to use. See e.g. https://true-myth.js.org – and when we built this, we did not publicize it or ship a 1.0 till every single item was documented.

I'm not looking for perfect docs; that doesn't exist. It's something you can always improve.

I'm just looking for any docs.

Re: Apple Developer Documentation Is Missing

#33

Post by DagAgren » Mon, Oct 28, 2019, 2:07 PM UTC

tpush wrote: post #14

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…

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.

Re: Apple Developer Documentation Is Missing

#34

Post by Phillips126 » Mon, Oct 28, 2019, 2:07 PM UTC

Docs are always something I evaluate before moving forward with a specific tool or language for a project. I have not done much work in the Apple ecosystem but it surprises me that a company of this size would have lackluster docs. It makes me wonder how many non-Apple developers give up on their idea for an app due to frustration and how that translates to lost profit for Apple given their 30% cut.

I am not a huge Golang fan but recently I found myself using Go quite a bit and I really appreciate their docs which include a description of each function and an example. The example code is even editable with a "Run" button so you could test and understand the function much better before moving it to your own code. Here's an example if you are unfamiliar with Golang docs (click the "example" link for the editable code): https://golang.org/pkg/strings/#Compare

Re: Apple Developer Documentation Is Missing

#35

Post by jasonlotito » Mon, Oct 28, 2019, 2:07 PM UTC

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've been working on implementing Apple Sign In on the server side. While the iOS side seems to be simple enough, their server side documentation is horrible. I can't imagine anyone actually used the documentation to implement Apple Sign In, and instead had to trial and error their way through it, relying on Googling well and finding other similar solutions.

This is sad, because if Apple wants Apple Sign In to succeed, you'd think they want to make this as easy to implement as possible. Instead, they relying on simply rely on mandating it's use in iOS Apps.

Re: Apple Developer Documentation Is Missing

#36

Post by swix » Mon, Oct 28, 2019, 2:08 PM UTC

cwbrandsma wrote: post #21

macinjosh wrote: post #8

Earlier quoted context omitted.

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

You, and them, are not their work. Both are subject to constraints of time, manpower, and talent. I don’t believe the issue is with the employees as much as the company not investing enough in that area. When you see a company with the resources Apple has, you expect to see better from them. Secondary example is XCode, their IDE. It is painfully obvious they don’t have enough people working on XCode.

Maybe the probblem is that they have too many people working on xcode, too many chefs in the kitchen usually produces mediocre results.

Re: Apple Developer Documentation Is Missing

#37

Post by AlexandrB » Mon, Oct 28, 2019, 2:09 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…

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?

Re: Apple Developer Documentation Is Missing

#38

Post by scarface74 » Mon, Oct 28, 2019, 2:09 PM UTC

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…

Listen to some podcasts with Marco Arment, the developer for Overcast and before that Instapaper. He details how bad the documentation is for some of Apple’s low level audio APIs and how it seems like no one at Apple has actually used some of the WatchOS APIs. Catalyst (Apple’s framework for porting iPad apps to the Mac) documentation is a constant source of complaint.

Swift UI’s error reporting is also obtuse.

Re: Apple Developer Documentation Is Missing

#39

Post by DagAgren » Mon, Oct 28, 2019, 2:10 PM UTC

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…

Well, he gives two examples. One is a framework first released about a month ago, in a great rush. The other is a tool that is not part of normal workflows, and is basically still in development.

I'm sure documentation will improve on both, and I've very rarely suffered from a lack of documentation when developing for Apple platforms. It has been a lot more pleasant to read than, for instance, Android documentation (although it has been a number of years since I did that, so it may have improved.)

Re: Apple Developer Documentation Is Missing

#40

Post by cyberferret » Mon, Oct 28, 2019, 2:10 PM UTC

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 ended up finding out more from a lot of third party blogs and via forums.

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