For what it's worth, something about the OS X Cocoa docs' arrangement
has never quite clicked with me. In part it might be an excess of
hyper text, too many pages to click through, breaking up the stream
of thought. (I wish XCode's doc viewer had some kind of keyboard
shortcut for clicking the 'next' or 'previous' links, rather than
having to scroll, find the link, and click on it. Surely it's
consistent enough to be automated?) I also get annoyed with
programming docs on Windows for the same reason - too much linky-
jumpy, too much documentation appearing to be little more than links
to yet other pages.
I found the arrangement of the NeXTStep docs to be a bit more
conducive to study. For one thing, the class reference docs were more
independently useful. Today the NSWindow class reference contains
method descriptions, but little context to help you make sense of
them. That context is in the Window Programming Guide For Cocoa,
which is itself 22 separate HTML pages, some of which are long
('Window Layering and Types of Window'), some short ('Handling Events
in Windows'). Some of the pages in the guide hardly seem long enough
to merit their own page. (That kinda bugs me. When a section gets its
own TOC entry, and its own page, but its only a short paragraph, I
think it leads the reader to feel a bit shortchanged, as if useful
information was left out. Worse, there might be relevant information
that is hiding elsewhere in the docs.)
In the NeXTSTEP days, a lot of that context information would be up
the top of the class reference file, so it was a self-contained unit
of information. There was also a set of Concepts documents that tied
things together, but there was a pretty high likelihood that a
question about a class could be answered simply by bringing up the
class reference rtf file. Need to know about NSWindow? Bring up
NSWindow.rtf.
Nowadays, the answer could be on any of a hundred pages, but probably
not in the class' own reference page.
(The NeXT docs were mostly set in Times, too, which I found easier to
read than the current near-universal use of sans serif.)
Your mileage may vary, of course. And I may be looking back through
rose-colored memories. I can't say the current arrangement is an
error or a case of bad design, it's just that I think the old
fashioned way worked better for my brain.
At the very least, before I got my hands on a NeXT box of my own I
was able to learn a fair amount from the NeXTStep Reference books,
two fat volumes consisting of the class reference files and little
else. The concepts material was in another volume. Nowadays, the
class reference files have largely been stripped down to
documentation of the methods, with little additional info, so there
would be little benefit from printing and binding them all together.
_______________________________________________
Cocoa-dev mailing list (Cocoa-dev@lists.apple.com)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com
This email sent to [EMAIL PROTECTED]
