Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Steve Weller <email@hidden>
- Date: Sun, 10 Jul 2005 19:36:38 -0700
At 2:23 AM +0200 7/11/05, Uli Kusterer wrote:
On Jul 11, 2005, at 1:07 , Steve Weller wrote:
A common thread I see through this discussion is that the
documentation mixes and confuses "what is achieved" with "how it is
done". A big improvement to the docs would be to clearly describe
everything separately in those terms:
Steve,
you're a genius! That is exactly what I've been trying to get a
grip on all this time. Though I'd also add "why" there; the issue
with a good bunch of the docs (at least as of 10.3 -- a lot has
already improved in the current batch) was that they *either*
contained "what" or "how" descriptions. We need both. And we need
"why". And in addition, we also need more information on what
certain methods don't do, or shouldn't be used for and what routines
to use instead. As in:
orderOut:
WHAT IT DOES: Hides the window from view.
HOW IT DOES IT: Takes the window out of the window list.
WHY: Use this to temporarily remove a window from display to quickly
show it again later without disposing of it, or to seemingly close a
utility window of which only a single instance exists.
THIS DOESN'T: Release the window object or remove any data
structures. For that, use closeWindow:. This also doesn't make a
window transparent. For that, see -isOpaque and setAlphaValue:.
In general, I think the reference docs could actually benefit from a
more rigid structure. Instead of embedding parameters in paragraphs
of text, make it a table that clearly labels input/output
parameters, who allocates them or disposes of them, and has links to
every data type of every parameter and what constants may be passed
there.
A rigid structure can make docs hard to read. You can fix this by
enforcing the rigidity in the database that stores the docs, but not
explicitly showing the structure in the output text. So WHAT IT DOES
and HOW IT DOES IT are just separate paragraphs (no headers or
titles). THIS DOESN'T is more formal and is actually headed that way.
WHAT IT DOES is actually not the best form, since searches will be
for "hide window", not "hides window". Better is to use the
imperative for the text and a prompt of "WITH THIS YOU CAN:" "Hide a
window" follows.
--
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