On 16 May '08, at 7:57 AM, john darnell wrote:
And, what I hear from this august crowd is a consensus that the references are difficult to understand, but necessarily so--that they ought to be that way.
I see your point, but I think you're phrasing it in a way that sounds overly contentious.
No one style of documentation is going to work for every person in every circumstance. An inexperienced programmer will need a tutorial introduction that explains basic concepts. (Even then, different people have different learning styles: some do best with step-by-step instructions, some need visual guides, etc.) A more experienced programmer will find the tutorial too slow to wade through and wants a more terse overview that explains the new concepts while taking the basics as understood. And a programmer who's gone through the overview and used the software needs a reference that describes every single feature in detail.
Apple doesn't have the resources to write every kind of documentation. Especially not when it's all given away for free! So the highest priority is given to the API references (since almost no one can figure out a new API without them), and most of the rest of the work goes into the "Programming Guide" overviews, plus some tutorials. The very introductory materials are left for 3rd parties, who have definitely picked up the ball.
When you say "difficult to understand", you mean "difficult to understand for a newbie". That's not a value judgment I'm making: I'm just pointing out that no one style of docs will work for everyone. The docs that are best for newbies would be really difficult for experienced people.
Example: I took an Economics 101 class in college. The textbook was good, except that it only used high-school algebra. At one point it went through about two pages of analogies and hand-waving to explain the concept of "marginal costs". It was really confusing me, until I realized that marginal cost is a derivative function. It would have been much easier for me to learn the concept if they had explained it in one line of differential calculus, instead of two pages of algebra. But of course, that was my opinion as a junior majoring in engineering; most business majors taking that class as a frosh would have been frightened away by calculus, so the book was appropriate for them.
Face it: programming is hard. Just like architecture, or music, or chemistry, or paleontology, or medicine. Anything hard is going to be, to some degree, hard to learn. No textbook or documentation will eliminate that. If you want to learn something hard, you've got to put in effort and deal with confusion and be persistent.
This is a debate that has been going on since I bought my first CP/M computer back in the early eighties.
CP/M sucks, dude! I bet your computer doesn't even have hi-res graphics. Apple ][ forever!!! ;-)
—Jens
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ 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]
