The potential audience for a computer programming documentation can range from beginner's who don't know what a compiler is to people who are experts themselves and just want a quick reference. Beginners are frustrated when prerequisite knowledge is assumed, and experts are frustrated when they have to search through redundant introductory material in order to find the nugget they seek. In the middle of that spectrum are programmers who are expert users of other frameworks. These programmers often want a quick translation guide. "I would do such and such this way using that framework; how can I do it with Cocoa?" Sometimes we even see programmers in the various forums complain that Cocoa works differently than some other framework. I don't know how to respond to that other than say, "Yup, Cocoa works differently than that." Authors have an additional challenge when writing on-line documentation. With a printed book, it is usually safe to assume that readers start at the beginning or will at least flip back a few chapters if they get lost. Readers come to on-line documentation in seemingly random order. A single search might identify twenty pages of information at various points along the spectrum from beginner to expert. The odds are _not_ in the author's favor that readers will understand the prerequisites and context needed to understand a page found at random. Once again, a newbie who chances upon expert level documentation will be frustrated and report that the documentation isn't helpful. An expert who finds extremely introductory information will complain that the documentation is too bulky and it's too hard to find information. Cocoa presents yet another challenge. In most respects, Cocoa is not an al-la-cart framework. There are key design patterns, repeated idioms, optional conventions, and most importantly some essential conventions. No matter how much experience a programmer may have, if the programmer fails to adhere to essential conventions (like Cocoa memory management conventions), they will not succeed with Cocoa. It is common that an experienced programmer will get started by searching Apple's on-line documentation and miss critical details. A symptom of this phenomenon is a mailing list post claiming that NSMutableDictionary is broken because the class is following essential conventions that the programmer isn't. As an aside, this phenomenon is not unique to Cocoa. I recall similar postings regarding Microsoft's IUnknow COM interface in COM mailing lists. I remember postings to device driver mailing lists indicating that the poster had some very strange conceptions about what a device driver is. It seems common to me that programmers who are completely unfamiliar with graphics programming will get upset about one detail or another of a graphics API particularly when mathematics are required. My point is only that Apple's Cocoa documentation and mailing lists are not the only ones to suffer from criticisms in the various categories I have described. Back to the subject: there is yet another problem: "I just want to do such and such? Why is it so hard?" These questions often prompt the "why do you want to do that?" or "don't fight the frameworks" or "what are you really trying to do?" responses. I don't think any kind of documentation can avoid these questions or answer them. Sometimes the question is along the lines of "I just want to build a launch vehicle that will put my neighbor's dog into space. It's not as if I want the dog to survive. why is it so hard?" What kind of book can really answer that kind of question? The bottom line is that Apple's conceptual documentation is very good. The only real problem is that people happen upon the conceptual documentation in random order or are too impatient to read it. The information is in there. Apple's reference documentation is also quite good, but it assumes that readers are familiar with the conceptual documentation or at least the critical concepts. Apple has tried to satisfy the needs of both novices and experts and actually succeeds reasonably well in spite of the challenges. Because Cocoa is a cohesive system that is astoundingly consistent, a programmer who groks it can correctly guess class and method names, anticipate potential error cases, avoid unnecessary code, and benefit from legendary productivity. A programmer who is missing one or more key concepts will find seeming barriers everywhere because Cocoa probably applies the concept ubiquitously. [Re-post from http://www.cocoabuilder.com/archive/message/cocoa/2007/8/20/188026] _______________________________________________
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]
