Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: mmalcolm crawford <email@hidden>
- Date: Sat, 9 Jul 2005 21:48:11 -0700
On Jul 9, 2005, at 6:45 PM, Andy Lee wrote:
On Jul 9, 2005, at 12:34 AM, mmalcolm crawford wrote:
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 these links, which are generally in a class's "Programming
Topics" section, are a good thing. It is helpful to have pointers
from very specific documentation to the more general conceptual
stuff. Multiple classes that relate to a general topic can point
to that topic, and the topic can in turn point to all its related
classes.
OK, thanks.
Perhaps another link could be added to that section called "Sample
Code"? And maybe another called "Tech Notes"?
I *think* this should be possible to do (although I'm not sure it can
be automatic) -- please file an enhancement request.
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.
I don't know about Apple's apps, but I think the code for even the
sample developer apps is less useful than it could be. IMO, sample
apps should be meticulously documented, and formatted for clarity,
with comments that are *more* expository than companies normally
use for internal code (which in practice often cuts corners in
documentation, though I personally don't believe it should). The
classes and methods in the sample code should be documented with
the same thoroughness, consistency, and quality of writing as any
AppKit class. And the code should be impeccably formatted and free
of sloppy tics (little things like using NULL when nil is better
style-wise).
This is certainly the goal that is aimed for, and I hope more recent
samples have been better at this, but where the goal is not achieved
it should be considered a bug...
I remember the Sketch code from the NEXTSTEP days. I was indeed a
bit overwhelmed. But I would be have less overwhelmed if it had
been documented as cleanly as the AppKit classes (and, frankly, if
the code had been cleaner).
Fair comment -- hence in part my suggestion for a guided tour for
Core Recipes.
I wouldn't write off the idea of a Smalltalk-like code browser, but
my thoughts there quickly run off-topic...
Provided that it's relevant to Cocoa, and making learning Cocoa
easier or the Cocoa documentation better, it should be OK.
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