This is really a fascinating discussion and, unfortunately, a time
consuming one =)
I can't help but feel that we have two identifiable camps forming, and
I'm not sure I like that. Though a range of opinions have been stated,
it seems that most of us can be readily identified as being on one
side or the other of this "quality of documentation" debate. I'm
really racking my brains to figure out why - why such a division? And
I hesitate to state some of my observations because they are likely to
be perceived by some as critical. Let me just say that it is not my
intention to put anybody down. I'm honestly interested in helping
people get over the steep learning curve, and if I say something that
irks you, please take a deep breath or two before getting upset with
me because I'm just trying to figure out the same thing you are, just
maybe from a different perspective.
Here's what I think is happening. You are welcome to disagree, if I'm
wrong it wouldn't be the first time. Anyway, coming to Cocoa now is
not like coming to Cocoa eight years ago when I did, or coming to
NextSTEP fifteen years ago like several people on this list. Much of
the conceptual underpinnings have remained constant — the same design
patterns are used over and over, and there's a conceptual consistency
in the Cocoa frameworks that I don't think you see in either Java
or .Net. Both of those languages & frameworks are more discreetly
divided up and are easier to dissect into digestible pieces. Now,
those of us who are comfortable with Cocoa and Objective-C don't often
experience more than mild discomfort when a new framework comes out or
a new OS release changes existing functionality. Usually there's one
or two conceptual hurdles, and then we're back to our comfort zone.
But over the years, I think Cocoa has become larger than some of us
realize, and I think we have to recognize that it is more daunting now
than it ever has been in the past to be a newcomer. The complexity
makes it harder to form a gestalt... to get a good high-level picture
of what's going on. I think it's still true that once you have that
30,000 foot view, it's really quite a nice language to work in with a
lot of benefits and, yes, some weaknesses.
I don't think it's possible for me, or those with even more experience
using Cocoa/Objective-C to grok what it's like coming to it now, and
perhaps we're a little insensitive to the plight of newcomers as a
result.
On the other hand, I think that at least some people coming to Cocoa
right now are getting unsettled by the complexity and the fact that
there are substantial differences from what they've done before,
causing them to be way outside of their programming comfort zone,
perhaps for the first time in many years. Maybe I'm wrong, but it
looks to me like at least some people are looking to blame the
documentation more than is fair. By "fair", I mean a few things.
First, how much are you paying for the documentation? How much did you
pay for the IDE? I mean, I'd love everything to be perfect for
everybody, but let's be realistic here. Apple doesn't derive any
direct income from the documentation or from Xcode, and as much as we
might think that shouldn't matter, Apple's a corporation, so it's
going to matter. That's reality, and it's not going to change.
Resources are limited, and considering the resources that are
available for API documentation, I think they do a phenomenal job, and
I honestly hate that some of the comments in this thread could be read
as disparaging their work, even if unintentionally.
Secondly, people learn differently. Not everybody learns at the same
speed or in the same way. That's the challenge of any kind of
education, and it's especially pronounced when you're creating
searchable, hyperlinked documentation, which has all the drawbacks of
written documentation, but without being able to rely on the fact that
the reader is going to go through the documentation sequentially.
Thirdly, who is the target audience for the documentation. As long as
OS X has existed, there's been a fairly stable, slowly growing group
of developers, many of whom know each other and support each other
here and at things like CocoaHeads and NSCoder nights. This recent
influx of new coders is quite a sudden change to the demographic.
Apple can't be expected to adjust to that change instantaneously. I
don't think it's even completely clear yet who's coming to the
platform right now and why. To the extent that people are trying to
give feedback to Apple so they know how best to proceed with future
revisions to the documentation, I think this discussion is valuable,
but at times we veer dangerously close to a pissing match mentality,
and when that happens, I don't think it's productive (even when it's
me doing it :) )
To put it bluntly, getting to a point where you truly understand the
fundamentals of Cocoa is hard. It's harder now than it has ever been,
and there aren't many shortcuts. There is no way to avoid a period of
confusion and frustration. You can't just learn one part of the API in
a vacuum like you can with some languages and libraries; the parts are
not discreet. It's like a giant jigsaw puzzle. That's not a fault of
the documentation, it's not even a "fault" at all - it's the way it's
been designed, it's the result of intentional design decisions. Once
you get past the hump, you'll soon forget how hard it was to get over
it, and that's really the only solace that can be offered if you're
struggling right now. Different or "better" documentation might help
you a little to get over that hump, but not as much as you probably
think. Even if individual pieces of the functionality were explained
better or in a way that's better for you, your brain still needs to
fit all those disparate pieces into the big picture before it all
starts to make sense, which just takes time and experience and making
mistakes. But it's very cool when the pieces do drop into place. It's
like a light turns on, it really is.
Now, if you're having a hard time with the documentation, and the
third party books aren't closing the gap for you, maybe you should
consider something like the classes at the Big Nerd Ranch, where you
can get direct feedback and answers from people who do have the big
picture and can work with you to help you get it too. It's probably
the fastest way to get over the hump. Though this list is tremendously
helpful, it's really better for answering concrete technical questions
than theoretical or conceptual ones, which rarely yield the answer
you're looking for, and often lead to long-winded discussions like
this one ;)
Well, I think that's enough said by me for now. I'm going to bed. Nite.
Jeff
_______________________________________________
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]
