On May 21, 2008, at 12:49 AM, Jeff LaMarche wrote:
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?
I think one of the major issues is that we're gaining new developers
at an extraordinary rate. And everyone learns differently as you say
later.
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.
I'm not sure that how much is being 'paid' for the documentation is a
valid metric.
I believe (not speaking for the company of course) that both of these
areas are viewed as investments.
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.
This consideration is much appreciated. But I think that most of us
find that this type of feedback (even when it could be negative) is
useful to what our mission is... giving developers the documentation
they need to write their apps.
We sort of have to aim our documentation at the mid range developer in
many cases. We don't have the facilities to teach basic C or OOP
technologies. Sometimes the basics of a technology aren't documented
well enough for all external developers (or internal for that matter)
to grasp, and we just need to know that.
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 :) )
One point that I'd want to make very clear to everyone (and it has
been said over and over) the list is not an official means for
providing this type of feedback to Apple. While many of us read it
and an benefit from the information we can glean from the list and the
users, it's direct contact with Apple via bug reports, enhancement
requests (via bugreporter) and the documentation feedback mechanism,
that is going to make a significant impact.
_______________________________________________
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]
