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

71–80 of 400 posts

Re: Apple Developer Documentation Is Missing

#71

Post by chriskrycho »

DagAgren wrote: post #62
chriskrycho wrote: post #47

Earlier quoted context omitted.

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 artic…

It is part of the Swift project, but it is not really part of the Apple development ecosystem. It might at some point be, but it is not now, and it is a small side project. And it is not, in general, used when developing for the ecosystem. And you may feel that way about docs, but it is not reasonable to find one single rushed release, and use that as an argument against the entire ecosystem. That is not a reasonable…

This isn't one single rushed release. This is perhaps the worst example at present, but it's not particularly unusual: https://nooverviewavailable.com

Re: Apple Developer Documentation Is Missing

#72

Post by fortran77 »

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. /s

I think you're proving his point. Apple, and the larger Apple community, simple doesn't' care about people who don't drink the Kool-Aid, and they mock and insult dissenters (as you did).

Re: Apple Developer Documentation Is Missing

#73

Post by moron4hire »

nullandvoid wrote: post #56
craydandy wrote: post #42

Earlier quoted context omitted.

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

Seriously, Apple is one of the richest companies in the world (I don't remember if it's still The Richest or not). Similarly, Google's documentation is pretty bad, considering just how ludicrously rich they are. They could afford to hire entire teams whose only jobs were to write documentation and it would barely make a blip in their bottom lines.

In contrast, I've always found Microsoft's documentation to be incredible. It can often be hard to find the right thing (though that has getting better, though that might be just my growing experience on how to find things), but they put real, actual effort into documentation.

Also, Microsoft has a very strong "corporate style guide" for API design. Every MS API within their major silos is built exactly the same way as every other API. Once you've had some experience with them, it's easy to figure out the others. I find Android to be down-right schizophrenic in comparison.

It's one of the many reasons I continue to focus on MS platforms for my work. It's been 20 years since they were the hostile "kill everything that moves" company that people lament.

Re: Apple Developer Documentation Is Missing

#74

Post by jtchang »

ChrisMarshallNY wrote: post #70

Some time ago, I was contacted by Apple to apply for a job. My code is insanely well-documented. I like to think that a lot of the inspiration for my code docs comes from Apple's open codebases. Their code is exceptionally well-documented. In any case, as is usual with all employers, these days, they completely ignored the focused, relevant links that I sent them to elements of my extensive portfolio of repos, and, i…

What is a "cascaded nil-coalescing operator" ?

Re: Apple Developer Documentation Is Missing

#75

Post by protomyth »

oflannabhra wrote: post #18

A couple years ago, maybe around Swift's debut, Apple began to mark all their sample code, projects, programming guides, technical notes, etc, as deprecated and unmaintained with a header on each page stating so, and putting it all in their "Documentation Archive" [0] They've had a new push to make sure that the remaining official documentation is available in either Swift or Objective-C, but I have yet to see any at…

Along with this, they removed or not generated PDFs like they once had. This is really painful for folks that have problems with looking at a screen for an extended period. They don't even have downloadable documentation that can be read on an iPad. The lack of PDF is a real issue for me.

The continued failing of example code is really painful.

Re: Apple Developer Documentation Is Missing

#76

Post by fireattack »

jk563 wrote: post #11
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?

And the author acknowledges that those individuals are not the problem. > the problem is not individual engineers — who are not responsible for writing docs; that is the responsibility of dedicated coumentation teams. But that does not make it any less a failure of Apple’s engineering organization.

I get author's point, but this sentence reads weird.

If a team ("dedicated [documentation team]") is responsible for something, surely the individuals in such team are responsible too? Or the author is making a distinction between "engineers" and team members of documentation teams?

Re: Apple Developer Documentation Is Missing

#78

Post by andybak »

iainmerrick wrote: post #23
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 d…

> usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag.

Ah - the "repeat the method names with spaces in it" style of documentation.

This is merely an exaggerated form of a trap that the majority of documentation falls into to some degree - documenting the "what" but neglecting the "why" or "how".

It tells you the bit you can easily work out by intuition, reading the source or using your IDE's features.

And it leaves out the really important parts: "how should I use this method?" and "why would I need to?"

Method based documentation also has problems explaining how API calls are used in concert. Understanding each method in isolation something leaves huge gaps in understanding how they are to be used together.

And no - you can't plug the gaps with lazy video tutorials.

Re: Apple Developer Documentation Is Missing

#79

Post by Ididntdothis »

jrochkind1 wrote: post #45

15+ years ago, Apple had some of the BEST documentation. But I agree it's fallen precipitously.

I worked a little on the Mac in the 90s and then their documentation was really good. You could read it like a book. Actually Microsoft was really good back then too with the MSDN library CDs they shipped. Not it’s pretty bad and getting worse all the time with a lot of broken links and tons of auto generated content that doesn’t explain the big picture.

Re: Apple Developer Documentation Is Missing

#80

Post by omaranto »

jtchang wrote: post #74
ChrisMarshallNY wrote: post #70

Some time ago, I was contacted by Apple to apply for a job. My code is insanely well-documented. I like to think that a lot of the inspiration for my code docs comes from Apple's open codebases. Their code is exceptionally well-documented. In any case, as is usual with all employers, these days, they completely ignored the focused, relevant links that I sent them to elements of my extensive portfolio of repos, and, i…

What is a "cascaded nil-coalescing operator" ?

Something like a.?b.?c which is syntactic sugar for:

    a && a.b && a.b.c
(with a short-circuiting &&.)
Post reply on HN