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

21–30 of 400 posts

Re: Apple Developer Documentation Is Missing

#21

Post by cwbrandsma »

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?

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.

Re: Apple Developer Documentation Is Missing

#22

Post by bitpush »

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?

I took a look at your comment history and you seem to be OK painting broad strokes on companies/institutions that you do not particularly enjoy. At one instance you were directly attacking a user.

It is clear, from your username, you like Apple. But ask yourselves whether you are being fair to the OP here.

Re: Apple Developer Documentation Is Missing

#23

Post by iainmerrick »

travisgriggs wrote: post #10

I work half and half pretty much maintaining the same app in both iOS and Android. Since the introduction of Swift, the Apple docs have become much terser (it's like Jony Ives slimness fettish got a hold of them). Even with that, they're better (by far) than what I find with the Android docs. The Android docs "explain" very little.

Android suffers a lot from quantity over quality. Classes are usually documented, but usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag.

Edit to add: I also work on both platforms, and I’d say iOS (along with MacOS) is usually easier to work with because the design tends to be sane and the names are fairly descriptive; whereas Android has a lot of weird and questionable design decisions so it’s harder to guess how things really work. On the upside for Android, it’s often possible to just read the source code (at least for the core OS).

I think the docs are about equally bad overall.

Re: Apple Developer Documentation Is Missing

#24

Post by boris »

Their diagnostics is pretty cool, though. How about this gem:

  ld: warning: ignoring file build2/libb.u.a, building for macOS-x86_64 but attempting to link with file built for unknown-unsupported file format
Going to steal that "unknown-unsupported" term for sure.

Re: Apple Developer Documentation Is Missing

#27

Post by scarface74 »

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…

Most developers who are making apps for iOS are working for companies that only care about money. There is no fanaticism about it. If developers optimized for working on platforms they liked, no one would write console games.

Re: Apple Developer Documentation Is Missing

#28

Post by WrtCdEvrydy »

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.

Re: Apple Developer Documentation Is Missing

#29

Post by OskarS »

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?

It's perfectly reasonable to say that a company of Apple's magnitude should invest in making sure their APIs are well documented. We're not talking about OSS projects with donated developer time.

Re: Apple Developer Documentation Is Missing

#30

Post by escape_goat »

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 frequently searching video transcripts to find information unavailable in the documentation.

I think that, if these claims are true, it does not reflect a good state of affairs, and that the extra work imposed on the individual developer is worth complaining about.

I don't think that he is calling out the work of the technical writers in any unsociable or shameful fashion in the text of his blog post. I agree that 'garbage' is not a good metaphor for "woefully inadequate," as it implies that the existing documentation would be better disposed of than referred to. However, I think that when dealing with a large software corporation that has teams dedicated to writing and maintaining technical documentation, it is not especially cruel or unfair to use hyperbolic language in calling extraordinary lapses to public attention.

Post reply on HN