Re: AppKit source available as reference?
Re: AppKit source available as reference?
- Subject: Re: AppKit source available as reference?
- From: jgo <email@hidden>
- Date: Thu, 5 Jul 2001 10:39:44 -0700
>
2001-07-01 23:38:10 -0500 Jonathan Hendry wrote:
>
> On Sunday, 2001 July 1 at 10:01 , Candide Kemmler wrote:
>
>> Le samedi 30 juin 2001, ` 11:54, Erik M. Buck a icrit :
>
>> Would anyone care to identify "good" documentation?...
>
>
>
> good documentation is cross-referenced, and makes use of
>
> hyperlinks: when a function returns an object that's also
>
> documented, a link is provided to jump to that object's
>
> documentation. ditho for the parameters,...
>
>
I'd have to disagree. There's some truly awful hyperlinked
>
documentation...
>
>
I think the presence of hyperlinks can lead tech writers to put too
>
little detail into the documentation, because more information is
>
available at the end of the link. The existence of more information
>
at the end of a hyperlink doesn't imply that that information is
>
what is _needed_ where the hyperlink appears. (Did that make sense?)...
Yes. A lot of times there needs to be explanatory material at
each place that has the different approach required by that
context. But you should still be able to select a class name
or type that is used, e.g. for a parameter, and jump to where
that is described.
>
jh from another post:
>
I'd rather have pages that are too big than pages that are too little.
I've seen both extremes in the Cocoa docs. Part of the problem is
these teeny tiny low-res displays we have to work with, so that
you can't juxtapose enough or the right things visually. I want to
have that 8.5 x 11 diagram fully visible on the left while I scroll
through the explanatory text and another related doc to the right
of that, for instance. That's why paper still beats on-line.
I can have 3 or 4 pages marked and several volumes laid out and
visible at the same time, so that I'm looking at the equivalent
of, let's see, (3000dpi * 9 inches (to simplify)) squared * say
4 pages open on a table, so we're talking about 3 billion pixels
at the same time, while now I've got less than 1 million pixels
on this screen.
That philosophy of atomistic, hyper-linked docs evolved from
the MIT practice of developers keeping a loose-leaf binder
next to the console to add their succinct pages. They seem
to have tried to limit themselves to as few pages as possible,
so there wasn't much explanatory material in the UNIX docs
I was seeing in the mid-1980s (yah, I know umpteen years after
the beginning).
(ooh, you've reminded me of something I haven't seen since the
end of the old paper days & beginning to use interactive debuggers.
It used to be possible to get a list -- somewhat analogous to a
batch search list -- that would lay out the life-time of a
particular variable: it has this type, it's declared here, set
in these places by an assignment, in those by an input operation,
and accessed in those places. Now, it'd have to be something like:
this object is of that class and is inited this way here
and there, assigned in that other place, copied... so you
wouldn't be doing a batch search on each of its init methods,
etc. and then trying to switch back & forth between multiple
result windows to figure out the object's life story.)
Have you ever worked on a program where you see comments and
function/method names that go through layers and layers of
"preparing to do x", and then "now that x is done", only
you can't see where x actually is done? It's not commented
and sometimes not even really there.* It's the same with
external documentation sometimes, where you're lead on an
elaborate hyper-path with no clear end. What we need are
those clear ends.
(And I need to get my dev work done and find some more time to
spend looking at the docs that exist rather than just struggling
to keep up with these e-mail lists. I've still got 50 pages to
go in _LC_. The last half needs more illos. There are screen-
shots early on that don't include certain things, and then the
reader is expected to extrapolate & muck about to find the
needed palette or whatever. Some of the screen shots could
be made smaller so as to, hopefully, fit on the same pages
with the text that refers to them.)
*One system I used had the equivalent of a tiny number of
tool-box calls that you prepared by setting some registers
and storing one of them into a low-memory address... no
return-jump, no conditional branch, no jump at all, and
then another program on another processor took over the flow
of execution until it picked up right where you left off,
only the requested value was in a register, so there wasn't
a fetch from memory, either. You just stored something and
then picked up the value. Spooky that first time.
John G. Otto Nisus Software, Engineering
www.infoclick.com www.mathhelp.com www.nisus.com software4usa.com
EasyAlarms PowerSleuth NisusEMail NisusWriter MailKeeper QUED/M
Will program Macs for food.