Cocoa mail archive
Re: Guidance for Cocoa's steep learning curve
FROM : Michael Ash
DATE : Fri May 16 15:49:21 2008
On Fri, May 16, 2008 at 9:30 PM, john darnell
<john.<email_removed>> wrote:
> I don't mean to be mean, but I agree with Joseph; most Apple
> documentation is really, really poor.
>
> *No, that's not correct.* The documentation is extensive, and
> comprehensive, but unless you already know what you are reading about,
> it might as well have been written in Farsi (no offense meant to any who
> speak Farsi--and if Farsi is your first language, then substitute
> English for Farsi).
>
> I have found this to be true on most every product's documentation; not
> just X Code. It is easily understood after five years of experience.
> The beginner struggles with the concepts, the locutions, the native
> phrases that the experienced programmer understands.
>
> For example, I was reading up on NSString yesterday and it began
> discussing "delegates." What the blazes is a delegate? (Please, no
> responses needed.) Open up any Developer page on the Apple site, and
> you run into the same thing. Concepts appear that are inadequately
> described, or described with so much jargon that even the experienced
> programmer (such as myself) has trouble making his way through it.
>
> Some of this might be better dealt with if the document were more
> extensively hyperlinked.
Massive hyperlinking would be nice, but you can make do without.
Google for "delegate site:developer.apple.com" and the first hit is
"Cocoa Fundamentals Guide: Delegates and Data Sources". This document
explains what delegates are and how to use them.
It's documentation, not a tutorial. It assumes you're relatively
fluent in the system as a whole, and doesn't try to teach you from
scratch. In other words, this is a feature, not a bug. I could
certainly see wanting more tutorials from Apple, but the documentation
itself does the job it's intended for pretty well. For now, if you're
after a tutorial, your best bet is probably to turn to third parties
in the form of Cocoa books.
Mike
DATE : Fri May 16 15:49:21 2008
On Fri, May 16, 2008 at 9:30 PM, john darnell
<john.<email_removed>> wrote:
> I don't mean to be mean, but I agree with Joseph; most Apple
> documentation is really, really poor.
>
> *No, that's not correct.* The documentation is extensive, and
> comprehensive, but unless you already know what you are reading about,
> it might as well have been written in Farsi (no offense meant to any who
> speak Farsi--and if Farsi is your first language, then substitute
> English for Farsi).
>
> I have found this to be true on most every product's documentation; not
> just X Code. It is easily understood after five years of experience.
> The beginner struggles with the concepts, the locutions, the native
> phrases that the experienced programmer understands.
>
> For example, I was reading up on NSString yesterday and it began
> discussing "delegates." What the blazes is a delegate? (Please, no
> responses needed.) Open up any Developer page on the Apple site, and
> you run into the same thing. Concepts appear that are inadequately
> described, or described with so much jargon that even the experienced
> programmer (such as myself) has trouble making his way through it.
>
> Some of this might be better dealt with if the document were more
> extensively hyperlinked.
Massive hyperlinking would be nice, but you can make do without.
Google for "delegate site:developer.apple.com" and the first hit is
"Cocoa Fundamentals Guide: Delegates and Data Sources". This document
explains what delegates are and how to use them.
It's documentation, not a tutorial. It assumes you're relatively
fluent in the system as a whole, and doesn't try to teach you from
scratch. In other words, this is a feature, not a bug. I could
certainly see wanting more tutorials from Apple, but the documentation
itself does the job it's intended for pretty well. For now, if you're
after a tutorial, your best bet is probably to turn to third parties
in the form of Cocoa books.
Mike
