Cocoa mail archive
Re: Guidance for Cocoa's steep learning curve
FROM : I. Savant
DATE : Fri May 16 15:57:51 2008
> 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.
I feel the need to chime in on this. I come from a very different
background than one would expect (if one read my posts to this list
regularly). I am entirely unschooled in this field and in some aspects
it shows very plainly. Yet I was writing production applications
within a few months. Some of which are still in use today with very
little changes. That would simply not have been possible without a)
the extensive and comparatively excellent documentation, b) a good API
reference browser (used to be CocoaBrowser, now I use AppKiDo - thanks
Andy Lee), and c) a few of the really good Cocoa books.
That said, the documentation is the reference manual. Let's
consider, though, why everything that comes with a huge manual also
spawns third-party books on the subject? Because anything that
complicated always needs a structured, "lesson-based" approach. That
is *NOT* the documentation's job. Not even the conceptual
documentation.
Your frustration is understandable (really, I felt a little lost in
the beginning too), but it most certainly does *NOT* take five years
to be able to effectively leverage the reference material available.
I apologize if this comes across as an attack (it's not meant as
such), but I find that assertion absurd. Had you said it takes five
years or so to become 'good at' Cocoa/Objective-C/XCode, I'd be less
inclined to object.
As an example, I know nothing of biology. Yet my current day job
consists of building and maintaining a Cocoa application used for
scientific research in the field of biology. I had no idea what a
'cytokine' was yet the specifications for the application I was to
design and build threw words like that around a lot. Wikipedia was my
friend, then "Bioinformatic for Dummies" (yes, I'm chuckling at myself
too, just having written that*). I'm still not a biologist nor will I
ever be, but it was up to me to do the research necessary.
* You think that's funny, you should've seen me presenting the beta
to biologists using an actual analysis. Though the application works
as advertised and has received nothing but glowing feedback, they had
a lot of questions I still couldn't answer.
> For example, I was reading up on NSString yesterday and it began
> discussing "delegates." What the blazes is a delegate? (Please, no
> responses needed.)
Like anything else that's highly technical, it's up to you to search
for definitions. Perhaps a universal glossary in the documentation
would help (file an enhancement request) but the very top of the main
Cocoa reference page lists the "Fundamentals" guide, which you are
meant to have read thoroughly. It contains this:
http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaFundamentals/CocoaDesignPatterns/chapter_5_section_3.html#//apple_ref/doc/uid/TP40002974-CH6-SW19
... an in-depth explanation of this mechanism. You CANNOT blame the
documentation for using "jargon" if you don't bother to read the very
basic introductory material.
> Some of this might be better dealt with if the document were more
> extensively hyperlinked.
Agreed. See below.
> At least Apple is going through the motions of attempting to get
> feedback from its users with the questions added at the bottom of their
> documentation. I hope that some day it does some good.
That's simply not fair. "Going through the motions"? The
documentation is regularly (every few months) refined and expanded
upon. They're not simply 'going through the motions'. As a Cocoa
developer of more than five years, I can speak from experience when I
say they're doing far, far more than 'going through the motions'. Even
simple spelling mistakes or incorrect punctuation are fixed pretty
quickly by using that 'feedback' box at the bottom of the page. I
believe in credit where it is due - especially when floundering in a
room full of very bright scientists.
--
I.S.
DATE : Fri May 16 15:57:51 2008
> 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.
I feel the need to chime in on this. I come from a very different
background than one would expect (if one read my posts to this list
regularly). I am entirely unschooled in this field and in some aspects
it shows very plainly. Yet I was writing production applications
within a few months. Some of which are still in use today with very
little changes. That would simply not have been possible without a)
the extensive and comparatively excellent documentation, b) a good API
reference browser (used to be CocoaBrowser, now I use AppKiDo - thanks
Andy Lee), and c) a few of the really good Cocoa books.
That said, the documentation is the reference manual. Let's
consider, though, why everything that comes with a huge manual also
spawns third-party books on the subject? Because anything that
complicated always needs a structured, "lesson-based" approach. That
is *NOT* the documentation's job. Not even the conceptual
documentation.
Your frustration is understandable (really, I felt a little lost in
the beginning too), but it most certainly does *NOT* take five years
to be able to effectively leverage the reference material available.
I apologize if this comes across as an attack (it's not meant as
such), but I find that assertion absurd. Had you said it takes five
years or so to become 'good at' Cocoa/Objective-C/XCode, I'd be less
inclined to object.
As an example, I know nothing of biology. Yet my current day job
consists of building and maintaining a Cocoa application used for
scientific research in the field of biology. I had no idea what a
'cytokine' was yet the specifications for the application I was to
design and build threw words like that around a lot. Wikipedia was my
friend, then "Bioinformatic for Dummies" (yes, I'm chuckling at myself
too, just having written that*). I'm still not a biologist nor will I
ever be, but it was up to me to do the research necessary.
* You think that's funny, you should've seen me presenting the beta
to biologists using an actual analysis. Though the application works
as advertised and has received nothing but glowing feedback, they had
a lot of questions I still couldn't answer.
> For example, I was reading up on NSString yesterday and it began
> discussing "delegates." What the blazes is a delegate? (Please, no
> responses needed.)
Like anything else that's highly technical, it's up to you to search
for definitions. Perhaps a universal glossary in the documentation
would help (file an enhancement request) but the very top of the main
Cocoa reference page lists the "Fundamentals" guide, which you are
meant to have read thoroughly. It contains this:
http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaFundamentals/CocoaDesignPatterns/chapter_5_section_3.html#//apple_ref/doc/uid/TP40002974-CH6-SW19
... an in-depth explanation of this mechanism. You CANNOT blame the
documentation for using "jargon" if you don't bother to read the very
basic introductory material.
> Some of this might be better dealt with if the document were more
> extensively hyperlinked.
Agreed. See below.
> At least Apple is going through the motions of attempting to get
> feedback from its users with the questions added at the bottom of their
> documentation. I hope that some day it does some good.
That's simply not fair. "Going through the motions"? The
documentation is regularly (every few months) refined and expanded
upon. They're not simply 'going through the motions'. As a Cocoa
developer of more than five years, I can speak from experience when I
say they're doing far, far more than 'going through the motions'. Even
simple spelling mistakes or incorrect punctuation are fixed pretty
quickly by using that 'feedback' box at the bottom of the page. I
believe in credit where it is due - especially when floundering in a
room full of very bright scientists.
--
I.S.
