Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Raffael Cavallaro <email@hidden>
- Date: Fri, 8 Jul 2005 18:20:41 -0400
On Jul 8, 2005, at Fri, Jul 8, 5:17 34 PM, mmalcolm crawford wrote:
I'd be particularly interested to know (again in the context of
Cocoa) in what sense you consider there not to be a "single,
authoritative source"?
One would expect that the reference documentation -
ADC Home > Reference Library > Documentation > Cocoa > Objective-C
Language > Application Kit Reference for Objective-C -
would be that single, authoritative source, but it is not:
First, take Stuart Malone's example of NSSound. The reference makes
no mention of any sound formats other than "AIFF, WAV, and NeXT
“.snd” files," but a tech note states that NSSound can play any
format that Quicktime supports. This rather important fact ought to
be in the reference but isn't. Apple should settle on a single type
of documentation as "authoritative" (I vote for the reference docs)
and make sure, as Stuart suggests, that these are kept up to date,
not added to by tech notes that developers may not even be aware exist.
Second, if the reference docs were that single, authoritative source,
they would contain sample code, rather than the current situation
with various sample snippets elsewhere in the documentation which the
reference docs don't even point to.
I think that most experienced developers benefit immensely from
short, concise example usages of Class methods, instance methods, and
demonstrations of how several classes are typically used together.
All of this information is available in the reference docs, but one
has to comb through a half dozen or more different locations across
two or three classes to get what could be had in a 5 or 10 line
example right there in the reference docs for the class in question.
Objective-C draws heavily on Smalltalk. Smalltalk programmers
typically learn best-practices usage by browsing their own image's
source code. Unfortunately, Xcode doesn't have a smalltalk style
source browser, and much of the interesting source code (e.g., the
source code to Apple's own Cocoa apps) is simply unavailable. Since
these sort of ready made easily browsed, examples are not there for
Objective-C, the Cocoa reference docs need a set of examples
demonstrating the best-practices usage of each class and instance
method of that class, and the most common usages of that class with
other Cocoa classes.
We acquire language mostly by example and much less so by being
taught the rules of our native language's grammar. The reference docs
now are more like an abstract grammar of the Cocoa frameworks. I
think they would be much more useful if they contained more
instruction by example in addition to the current instruction by
precept.
regards,
Ralph
Raffael Cavallaro, Ph.D.
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