> 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. _______________________________________________ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
