Re: Guidance for Cocoa's steep learning curve

FROM : Jeff LaMarche
DATE : Fri May 16 16:29:28 2008

On May 16, 2008, at 9:30 AM, john darnell wrote:

> 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'm curious what you're actually looking for in documentation; what 
you think Apple or Microsoft could do to make them better, because I'm 
having trouble accepting this premise and it seems to me that what you 
want is simply unrealistic. If they were able to make documentation 
that made you happy, my guess is that the most of us would hate it, 
because we'd have to slog through fundamental conceptual information 
in places where it doesn't belong.

I am not as familiar with Microsoft's documentation, but my limited 
experience with it has been fairly positive (as much as I hate to say 
anything good about Microsoft ;) ) and I find the Apple documentation 
to be excellent. There have been times where the documentation has 
lagged behind development and caused some difficulties for developers, 
especially in the early days of OS X, but overall, I think we are 
spoiled by the amount of information we have available to us. 
Personally, I think that the "Object-Oriented Programming with 
Objective-C" book on the developer website, which isn't all that 
changed from the NeXT days, contains one of the clearest explanations 
of the concepts underlying object-oriented programming that I've seen 
anywhere, and it is right where it belongs - that type of conceptual 
material doesn't belong in the API documentation.

Hand-holding guides exist; they're called books. Apple even offers 
several guides to conceptual information, but they are separate from 
the API documentation. Although I think a reasonably intelligent 
person could learn everything they needed to know from Apple's 
official documentation without using other books, those other books 
clearly exist for a reason, which is to shorten the learning curve a 
bit and gather up a lot of disparate information into one place. Like 
I. Savant, my educational background is not in programming, and I am 
pretty much self taught, so believe me, I understand the challenges of 
learning this stuff. You have to acquire the foundational knowledge, 
either from the Apple documentation, or from third-party books. You 
can't just expect to look at tiny pieces of the puzzle like the API 
documentation of a class and expect to magically get the big picture 
from it.

Documentation isn't magic. It can't be all things to all people. 
Considering the complexity and the target audience, I'd say that 
Apple's documentation is, frankly, stellar. Yes, often understanding 
one part will require you to do some research to understand a term or 
concept from another part of the system, or to sit down for a few 
hours and experiment, or maybe even ask a few questions here. If it 
could be made so simple that none of that was necessary (without 
sacrificing functionality), most of the people on this list would be 
out of a job or, at least, making less money. Too many people assume 
programming is (or should be) easier than it really is.