Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Charlton Wilbur <email@hidden>
- Date: Sat, 9 Jul 2005 03:05:55 -0400
On Jul 9, 2005, at 2:25 AM, Raffael Cavallaro wrote:
I agree that the docs seem to have been written with this attitude.
But this attitude - that there is a critical mass one needs to know
before the docs become useful - more or less defeats the purpose of
documentation. Documentation should be geared toward those who
don't know what the docs contain. After all, if you already know
what they say, you wouldn't be consulting them.
No, because there are different reasons for consulting
documentation. For instance, in the past week I've gone to the
documentation for several reasons --
* Overview. What can I do with this new Core Data stuff?
* An attempt to evaluate a particular class for a particular
problem. How does -forwardInvocation work, and how can I make it do
what I want?
* A specific detail about a method. I know there's a
NSNotificationCenter class method to send a notification, but I can
never remember what it's called or what arguments it takes.
In the past I've also gone to documentation for other things --
* Tutorial. Where do I begin with this Cocoa thing?
* Debugging. The program issues a warning when it compiles; what on
earth does it mean?
I think it's absurd to expect a single set of documentation to
satisfy all of these needs.
My solution was to get my hands on the Hillegass book and work
through it doggedly until I had enough of a foundation to discover
things from the documentation, then to refer to it for painstakingly
worked examples of other basic things that the Apple-provided
documentation assumed a better knowledge of than I had.
The documentation *can't* be all things to all people. At some
point, Apple needs to say, "this is the target audience," and write
to that target. In this case, they've chosen a reasonable target,
especially given that there are excellent introductory tutorials
available in print form to get new programmers to the point where
they understand Cocoa enough to handle the Apple-provided
documentation, and excellent universities, colleges, trade schools,
correspondence courses, and web tutorials to get non-programmers to
the point where they can understand the rudiments of programming.
In short, a new Cocoa programmer is best off getting his or her hands
on a tutorial-reference like the Hillegass and working through it.
The documentation is not designed for utter novices. Expecting it to
be is like expecting to learn C from section 2 manpages or expecting
to learn Perl from the perldocs; while you *can* do it, there are
much better ways to go about it. Further, rewriting the section 2
manpages and the perldocs so that they are novice-friendly (as
opposed to *adding* novice-friendly manpages and perldocs) is likely
to make them less useful to experts, because of all the wading
through explanations of basic concepts the experts will have to do.
There's also a cost-benefit analysis. I'd rather have a rock-solid
system with lots of useful features and adequate documentation than a
buggy, minimal system with documentation that would put the Big Gray
Wall to shame. To be sure, this is a continuum, but it's a complex
optimization problem; while I think the Apple documentation could do
a slightly better job of hitting its target, I think the target it's
aiming at is well chosen.
Apple have limited time and resources, and they are better off using
them to get adequate basic documentation for Cocoa-savvy people out
the door -- because they are the only ones who can do that step.
Other people -- the folks at www.cocoadev.com, the folks at O'Reilly,
Aaron Hillegass, the contributors to this list -- can translate that
documentation into novice-friendly formats.
I realize that the higher level conceptual docs are intended to get
one to this level of knowledge, but they fall short in my opinion
in that they do not provide extensive enough sample code to be
useful. As a result, I end up reading the API references, which
also unfortunately lack sufficient sample code. But at least the
API references have enough meat to allow one to figure out what the
relevant sample code would look like if it existed.
You're missing the third leg of the tripod -- the extensive sample
code that's already provided, in the form of sample programs. Most
of them are well-worked examples of how to do one or two tricky
things, and they all contain canonical examples of how to use the
Cocoa API. It might be nice if they were more prominently featured,
or cross-referenced in the API reference, or in the conceptual docs.
And aside from that, I'm wary of *extensive* sample code, because of
the novice practice of cut-and-paste coding. I've fixed enough Perl
code that otherwise seemingly intelligent coworkers have mindlessly
copied and pasted without understanding that I'm leery of providing a
body of sample code for otherwise seemingly intelligent people to
copy and paste without understanding.
Charlton
--
Charlton Wilbur
email@hidden
email@hidden
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden