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]

Reply via email to