On May 16, 2008, at 9:30 AM, john darnell wrote:
I don't mean to be mean, but I agree with Joseph; most Apple
documentation is really, really poor.
*No, that's not correct.* The documentation is extensive, and
comprehensive, but unless you already know what you are reading about,
it might as well have been written in Farsi (no offense meant to any
who
speak Farsi--and if Farsi is your first language, then substitute
English for Farsi).
I'm curious what you're actually looking for in documentation; what
you think Apple or Microsoft could do to make them better, because I'm
having trouble accepting this premise and it seems to me that what you
want is simply unrealistic. If they were able to make documentation
that made you happy, my guess is that the most of us would hate it,
because we'd have to slog through fundamental conceptual information
in places where it doesn't belong.
I am not as familiar with Microsoft's documentation, but my limited
experience with it has been fairly positive (as much as I hate to say
anything good about Microsoft ;) ) and I find the Apple documentation
to be excellent. There have been times where the documentation has
lagged behind development and caused some difficulties for developers,
especially in the early days of OS X, but overall, I think we are
spoiled by the amount of information we have available to us.
Personally, I think that the "Object-Oriented Programming with
Objective-C" book on the developer website, which isn't all that
changed from the NeXT days, contains one of the clearest explanations
of the concepts underlying object-oriented programming that I've seen
anywhere, and it is right where it belongs - that type of conceptual
material doesn't belong in the API documentation.
Hand-holding guides exist; they're called books. Apple even offers
several guides to conceptual information, but they are separate from
the API documentation. Although I think a reasonably intelligent
person could learn everything they needed to know from Apple's
official documentation without using other books, those other books
clearly exist for a reason, which is to shorten the learning curve a
bit and gather up a lot of disparate information into one place. Like
I. Savant, my educational background is not in programming, and I am
pretty much self taught, so believe me, I understand the challenges of
learning this stuff. You have to acquire the foundational knowledge,
either from the Apple documentation, or from third-party books. You
can't just expect to look at tiny pieces of the puzzle like the API
documentation of a class and expect to magically get the big picture
from it.
Documentation isn't magic. It can't be all things to all people.
Considering the complexity and the target audience, I'd say that
Apple's documentation is, frankly, stellar. Yes, often understanding
one part will require you to do some research to understand a term or
concept from another part of the system, or to sit down for a few
hours and experiment, or maybe even ask a few questions here. If it
could be made so simple that none of that was necessary (without
sacrificing functionality), most of the people on this list would be
out of a job or, at least, making less money. Too many people assume
programming is (or should be) easier than it really is.
_______________________________________________
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]
