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".
_______________________________________________
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]
