Re: Guidance for Cocoa's steep learning curve

FROM : Michael Vannorsdel
DATE : Fri May 16 17:41:24 2008

Tutorial examples don't really belong in API docs.  Their ultimate 
goal is to state the purpose and usage as directly as possible so the 
developer can get what they need and move on.  Continuously sifting 
through tutorial information and examples would be quite tedious and 
redundant for the majority who already understand the general concepts 
and conventions.

Apple does provide many introductory and advanced "booklets" that help 
to grasp the concepts and conventions.  Once you learn these and put 
everything together a lot of the APIs make sense, mostly because of 
Apple's adherence to these concepts and conventions (especially with 
Cocoa).

Some of the booklets take a little extra looking to find and may 
contain redundant or seemingly irrelevant information to what you're 
looking for.  But I've found that continuing to read on would produce 
little gems, or pieces of the puzzle if you will, that spark 
connections for you that you previously didn't make before.

Apple's tutorials are meant to be used as samples of applying the 
concepts you've read in the booklets.  You know the lingo and basic 
idea, now you get to see how it's applied in real examples.  If you 
haven't yet learned the idea concepts, the code tutorials won't do 
much for you.  You'll see what code is needed to carry out a certain 
task, but you won't know why the code was done as it is and won't 
recognize the application of the concepts and conventions.  The 
tutorial would be mostly fruitless.

Several books have been written that take different approaches to 
teaching the concepts and showing their applications.  Not everyone 
will learn from the exact same approach, and I don't believe it's 
possible to make a single approach that works for everyone.  Apple 
presents one approach and it won't work for everyone, and when it 
doesn't work for you, you search for different approaches.

Back in the college days I had taken two different courses on object 
oriented programming at two different universities.  Both books were 
400 pages+.  And sadly I still didn't quite understand the 
relationship of objects and classes and why anyone would need many 
copies (objects) of something made up of one group of code (a class). 
I had come from a procedural background and had a procedural mindset.

Then one day I got desperate and bought an online course presented in 
Shockwave.  It took me 3 days to complete the course.  Not because it 
was short, but so much was making sense and I was making so many 
connections that I couldn't stop and would work at it for 12-15 hours 
each day.  Afterwards OO programing made complete sense and I 
understood its purpose and possibilities.  For some reason that 
particular approach was just what I needed.

I don't blame the college courses nor do I think they were bad or 
worthless; They just weren't for me.  Apple's approach is not for 
everyone either but that doesn't invalidate its value.  I personally 
found it extremely helpful.


On May 16, 2008, at 8:27 AM, I. Savant wrote:

>  I don't think it's possible to continue a rational debate when you
> keep going down this type of path. Nobody here even remotely suggested
> that documentation should be hard to read. Conversely, nobody can
> reasonably argue that it is possible for documentation (on such a
> highly complex technical subject) to be made "easy".