Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Andy Lee <email@hidden>
- Date: Sat, 9 Jul 2005 21:45:58 -0400
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.
Perhaps another link could be added to that section called "Sample
Code"? And maybe another called "Tech Notes"?
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.
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).
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).
I wouldn't write off the idea of a Smalltalk-like code browser, but
my thoughts there quickly run off-topic...
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"...
The SimpleStickies example used to illustrate Sync Services has a
sort of tutorial progression where you are shown step by step how to
add features to a sync client. One thing I liked about this was that
the documentation *had* to discuss concepts in a way that I found
helpful.
--Andy
_______________________________________________
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