Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: m <email@hidden>
- Date: Sat, 9 Jul 2005 12:19:18 -0700
On Jul 8, 2005, at 11:25 PM, Raffael Cavallaro wrote:
I think what some of this boils down to is that there is a lot to
know, and that a critical mass of knowledge is required before you
can effectively bootstrap the rest.
I agree that the docs seem to have been written with this attitude.
But this attitude - that there is a critical mass one needs to know
before the docs become useful - more or less defeats the purpose of
documentation.
Well, no. The API docs' primary purpose is not to teach (though you
can learn from them), but to serve as a reference. They also (rightly
in my view) are geared to folks who already have some idea of what is
going on. After all, newbie-ness is but a temporary state.
Have you ever wondered what makes a good teacher? Very often, it's
not the quantity and depth of the teacher's knowledge, but the
teacher's ability to transmit knowledge and to teach you how to learn.
If you want to learn, don't be a cheapskate: bite the bullet and buy
a book that "teaches", not just one that "knows". If you can afford
it get both. I found the Hillegass book to be a really good
"teaching" book when I was learning, as was the book by Anguish,
Buck, and Yacktman. Both made "Cocoa In A Nutshell" and the API docs
a lot easier to navigate.
Documentation should be geared toward those who don't know what the
docs contain. After all, if you already know what they say, you
wouldn't be consulting them.
But you do need to know what it is that you don't know in order to be
able to navigate the docs, and this is the problem that the
"teaching" books do an admirable job of solving.
_murat
_______________________________________________
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