Cocoa mail archive
RE: Guidance for Cocoa's steep learning curve
FROM : john darnell
DATE : Fri May 16 15:30:24 2008
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.
Microsoft documentation is the same way--difficult to understand unless
you have learned the lingo. Borland documentation, I have found, is
not, but alas it has such a small market share that it is virtually
ignored.
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.
R,
John
-----Original Message-----
From: cocoa-dev-bounces+john.darnell=walsworth.<email_removed>
[mailto:cocoa-dev-bounces+john.darnell=walsworth.<email_removed>] On
Behalf Of Jens Alfke
Sent: Thursday, May 15, 2008 9:07 PM
To: Joseph Ayers
Cc: <email_removed>; mmalc crawford
Subject: Re: Guidance for Cocoa's steep learning curve
On 15 May '08, at 6:33 PM, Joseph Ayers wrote:
> What is absolutely
> baffling is dealing with NSTableView. The documentation absolutely
> sucks. How does one map table rows and columns
> on NSMutableArrays and NSMutableDictionaries. How does one map the
> Rows and Columns of a "dataSource"
> on a NSTable view?
I take it you read the table view programming guide and it didn't help?
file:///Developer/Documentation/DocSets/com.apple.ADC_Reference_Library.
CoreReference.docset/Contents/Resources/Documents/documentation/Cocoa/Co
nceptual/TableView/Tasks/UsingTableDataSource.html
DATE : Fri May 16 15:30:24 2008
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.
Microsoft documentation is the same way--difficult to understand unless
you have learned the lingo. Borland documentation, I have found, is
not, but alas it has such a small market share that it is virtually
ignored.
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.
R,
John
-----Original Message-----
From: cocoa-dev-bounces+john.darnell=walsworth.<email_removed>
[mailto:cocoa-dev-bounces+john.darnell=walsworth.<email_removed>] On
Behalf Of Jens Alfke
Sent: Thursday, May 15, 2008 9:07 PM
To: Joseph Ayers
Cc: <email_removed>; mmalc crawford
Subject: Re: Guidance for Cocoa's steep learning curve
On 15 May '08, at 6:33 PM, Joseph Ayers wrote:
> What is absolutely
> baffling is dealing with NSTableView. The documentation absolutely
> sucks. How does one map table rows and columns
> on NSMutableArrays and NSMutableDictionaries. How does one map the
> Rows and Columns of a "dataSource"
> on a NSTable view?
I take it you read the table view programming guide and it didn't help?
file:///Developer/Documentation/DocSets/com.apple.ADC_Reference_Library.
CoreReference.docset/Contents/Resources/Documents/documentation/Cocoa/Co
nceptual/TableView/Tasks/UsingTableDataSource.html
