Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: mmalcolm crawford <email@hidden>
- Date: Fri, 8 Jul 2005 21:34:29 -0700
On Jul 8, 2005, at 3:20 PM, Raffael Cavallaro wrote:
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:
No, it's the API reference for Application Kit.
The authoritative reference for Cocoa is ADC Home > Reference Library
> Documentation > Cocoa.
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.
I would regard this as a bug. Please file a bug report, if you
haven't already?
Do you have any other examples?
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.
In general, the API reference does point to the conceptual and task-
based documentation relevant to the class -- for example NSSound
points to the "Sound" document, NSView points to "Drawing and Views,"
"Basic Event Handling," "Drag and Drop," "Printing" and so on.
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.
In general I would *personally* agree, however:
(a) There in some cases there are already examples, such as in
NSView's description of
dragImage:at:offset:event:pasteboard:source:slideBack: <http://
developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/
ObjC_classic/Classes/NSView.html#//apple_ref/doc/uid/20000014-
BBCDEIEF> or NSManagedObjectContext's executeFetchRequest:error:
<http://developer.apple.com/documentation/Cocoa/Reference/
CoreData_ObjC/Classes/NSManagedObjectContext.html#//apple_ref/doc/uid/
TP30001182-BAJDFCJJ>
(b) It is often the case that the use of a particular method relies
on more context than just the immediate class.
Although the method description for executeFetchRequest:error: does
include a code sample, it could reasonably be argued that it should
also appear in the class documentation for NSFetchRequest, and there
could also be a case for including it in the preamble for NSPredicate.
This obviously quickly becomes unwieldy...
This is why in general the *reference* documentation is treated as a
dictionary, and why higher-level discussion and use-case examples are
grouped into other documents.
If you feel there are specific methods that would benefit from "in-
line" code examples, please file enhancement requests; similarly if
you feel that more sample code is needed in general...
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.
I strongly suspect that source code to Apple's apps would not be
useful as a learning tool. For a long time, Sketch was the primary
"repository" for much information for a "large"-scale application,
and most developers found it too overwhelming to find much useful
information. Even if you had the source code to, say, Mail, it would
probably take a significant amount of time to figure out the
application architecture before you could extract all the information
you needed to, say, create your own smart groups. We have within the
last day seen several people state that the Core Data example, Core
Recipes, not itself a particularly large or complex application,
could benefit from a "Guided Tour"...
There are also increasing numbers of example applications being made
available as part of the Reference Library. Searches of the
Reference Library now return these examples. There are even more in /
Developer/Examples. Collectively these should give plenty of
interesting source.
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.
Perhaps you could offer an example? What (in outline at least) would
be a "best practices" example of the method definition for NSView's
drawRect:?
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.
Again, in some cases these are present, and absence is not
necessarily a policy decision, but simply a result of there being
finite resources. If there are any areas that you feel need to be
addressed urgently, then please file enhancement requests.
mmalc
_______________________________________________
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