Re: bad documentation
Re: bad documentation
- Subject: Re: bad documentation
- From: Angela Brett <email@hidden>
- Date: Tue, 13 Nov 2001 15:17:14 +1300
One thing that I find very helpful is the fact that the AppKit and
Foundation both have their docs in PDF format. If you open them with
Acrobat Reader, you can quickly search through all of the AppKit or
all of the Foundation, without having to use Sherlock, the Help
Viewer, or a connection to the Internet. It's very nice - you might
want to try it.
I agree - I've always used the PDFs, they are easy to search and it's
very easy to see (in the bookmarks) what classes are available and
what methods each class has. I don't know how much is due to using
the PDFs, but I've been quite happy with the docs so far. There are
some 'Description Forthcoming's which can be annoying, but to be
fair, many of those are in places where there's really no need for
any description - particularly in the descriptions of types and
constants.
The main thing I think the documentation needs would be a mention in
the documentation for each class or method of which example projects
use that class or method. There seems to be a lack of examples, but I
think that in fact there are quite a lot of them in that 'Examples'
folder. They are just not mentioned in the documentation so it's hard
to find an example of how to use whichever specific class or method
you're looking at.
That's enough from me. It seems like half the posts on this list are
complaints about or defense of the documentation, and it's getting
rather tiresome, so I promise not to post on this topic again unless
someone wants me to clarify something I've said. We know the docs
will get better, Apple knows we want them to get better, so there's
not much point over-discussing them. Which makes me wonder why I'm
even going to send this email... I guess I'm just hoping people will
try using the PDFs and maybe that will make things a bit easier for
them. Sorry for rambling.
--
Angela Brett email@hidden
http://acronyms.co.nz/angela
A mathematician is a machine for turning coffee into theorems -- Paul Erdos