Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Steve Weller <email@hidden>
- Date: Sun, 10 Jul 2005 15:12:31 -0700
On Jul 7, 2005, at Thu, Jul 7, 3:26 52 AM, Todd Blanchard wrote:
I see that the docs are trying very hard to be complete and nooB
friendly. They do this at the expense of essential information and
the great annoyance of the experienced but busy. I would very much
like to see something that explains the interaction pattern,
exactly who calls what, what is already written, and what I have to
write, a brief but complete example, and that's it.
I think that this stands as a general issue with the Objective-C
docs in general. One gets a very newbie-friendly, but too high level
overview in the conceptual docs, and exhaustive rundown of every
ivar, class method and instance method in the reference docs, but
not much in the way of a practical picture of how things go
together in practice. One is reduced to jumping back and forth among
the class and instance method docs of a dozen different methods in
three or four different classes, plus the conceptual articles just
to get basic things done.
Todd's suggestion of "a brief but complete example" for each class
showing how it is used in practice with the rest of the frameworks
would be worth its weight in gold for those readers who already know
something about object oriented programming. To put it another way,
the idea that reference documentation would contain no sample code
at all is, to my mind, almost perversely frustrating.
In short, the current reference documentation scheme is too
fragmented and lacking in example code for practical use, and the
conceptual documentation is too elementary to do real work with.
What is needed is a middle ground - call it "practical" or "best
practices" that provides sample code that *systematically* covers
the most common uses of all classes. Linking to these "best
practices" samples from the reference documentation would be even
more useful.
I second this last paragraph. It hits the nail on the head.
I'm an experienced programmer, but not with Objective-C or Cocoa. So
I have holes in my comprehension and knowledge that are large and
glaring to me and don't have the material they need to get filled in.
Additionally I don't have much time to experiment to build the
frameworks in my head that I need to fully understand what I can
read. I have *much more* time available for reading documentation, so
if the right documentation were available to me all would become
clear.
Some specific suggestions regarding bindings, core data, etc.
* Take a simple example application and implement it in several
different ways: no bindings, bindings, Core Data.
* Give some example programs that instead of using complexity to show
off how clever the tools (such as Core Data) are, use simplicity to
show how they work. For the purpose of learning, hiding all the
clever stuff is not useful. For the purpose of getting work done it
is ideal.
* Provide a tool or feature that shows in some tabular or graphical
form ALL the curent bindings, key-value compliances, core data
connections, etc. for the project. Have it illustrate somehow what
the programmer has explicitly created, what the programmer has
implicitly created, and what the system has created or has already
implemented. Warn of anything that is incomplete, duplicated, or
contradictory.
One way of viewing programming is that of filling in the gap between
what the language, libraries, frameworks, etc. can do and what the
finished application should do. As the docs and tools stand now, it
is very hard to figure out the shape and size of that gap, change it,
and then get feedback as to what has been achieved without just
running the app and responding to runtime errors.
It would probably help if Apple sat down with some programmers in
some sort of study group and tried to understand the learning process
and how the documentation can fit into that.
--
How much art could an artichoke choke if an artichoke could choke art?
_______________________________________________
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