Re: Docs
Re: Docs
- Subject: Re: Docs
- From: Jonathan Hendry <email@hidden>
- Date: Thu, 23 Aug 2001 11:58:42 -0500
On Thursday, August 23, 2001, at 11:31 , Todd Heberlein wrote:
From: R. Tony Goold <email@hidden>
I'm inclined to agree with Searle. I see a lot of 'RTFM'
comments which seem inappropriate given the context,
Its appropriate. In this case it simply means
"Read The Forthcoming Manual"
It doesn't mean that when the questions deal with NSString,
NSArray, or other well-documented classes.
The forthcoming stuff tends to be in new material. Incidentally,
questions that deal with 'forthcoming' stuff tend to be questions
that stump everyone, because they _are_ new material and nobody
has much experience using them. Thus, questions that deal
with forthcoming documentation aren't going to get RTFM
answers.
I have to admit I am often surprised at how many descriptions for
methods are "forthcoming", and I do find that tends to discourage me
from looking. That is, the descriptions may be there, but I have
hit so
many brickwalls in the past that I am hesitant to invest lots of
time to
look for something.
I dunno, I don't hit forthcoming stuff very often. But then, I'm not
trying to do sound, music, video, OpenGL, or resource forks. That
doesn't mean I can't do useful work, it just means I'm using the
subset of reasonably-well documented functionality.
Also, with some things that are 'forthcoming', all you have to do is
just try it out and see what happens. Chances are good that it won't
trash your computer (as long as it's not filesystem-related), so go
ahead.
Maybe Mac developers tend not to take this route, because historically
it could make their Mac crash instantly.
Developers ought to take the same approach to learning an API
as they would to learning a GUI: poke around, play with things,
see what happens. There are limits, of course. This doesn't apply
to kernel extension development or to code that deals with writing
files. In those cases you have to be a little more careful.
And as always, use the headers, not the HTML docs.
Oddly, I do find something a bit more 'intimidating' when it's
described as
'forthcoming' in the HTML docs, but the same thing seems accessible when
I'm looking at the declaration in the header. Maybe because the
header puts
everything on an equal footing, whereas the 'forthcoming' note in
the HTML
makes those things stand out because everything else has actual
documentation.
The 'forthcoming' thing in the docs might also carry, for me, a
connotation
of 'not implemented yet'.
Personal quirk of mine, perhaps.
| References: | |
| | >Re: Docs (From: "Todd Heberlein" <email@hidden>) |