Re: AppKit source available as reference?
Re: AppKit source available as reference?
- Subject: Re: AppKit source available as reference?
- From: Jonathan Hendry <email@hidden>
- Date: Sun, 1 Jul 2001 23:38:10 -0500
On Sunday, July 1, 2001, 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 ? Would
anyone care to
identify a more consistent or clearer framework ?
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.
The Delphi class framework docs would be an example. They're in Windows
Help format.
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?)
Hyperlinks also seem to be used in place of a decent search
facility, which is a big mistake.
I always liked the old NeXT class documentation, which was
just rtf without links
I suggest that you don't need to go back to a framework's list of
classes everytime you want to consult another class'
documentation. Frames are a good option for this (why not get
inspiration from javadoc's format ?).
A good tool for viewing the docs helps in that case. I'd rather have
something like the old NeXT HeaderViewer program than just a list in
a frame. HeaderViewer had a hierarchical browser view of classes in
the top portion of the window; below that was a large area which
would display either a header or the documentation file for a
selected class.