Re: Man cannot rely on headers alone (was Re: Docs)
Re: Man cannot rely on headers alone (was Re: Docs)
- Subject: Re: Man cannot rely on headers alone (was Re: Docs)
- From: Georg Tuparev <email@hidden>
- Date: Sun, 26 Aug 2001 12:49:49 +0200
Ken,
I'm 100% with you. Headers should not be the documentation. But the word
"should" already implies, I'm afraid, wishful thinking. The pity state
of the industry (including Apple's) as I can see it, unfortunately does
not allow to have accurate developers documentation. When you have
deadlines set by marketing people without consulting the techies, and
when rules like "developers have to code, and technical writers have to
write documents" are the standard in large organizations, there is not
even a glimpse of hope one can ever expect accurate, up-to-date, and
useful documentation. I am not criticizing Apple, it is just the same
all over the industry. So, what can we do? Read headers, and hope to
find the right answers there. With danger to repeat myself, I will
reiterate, that at least Cocoa frameworks are in large very constant and
in many cases self explanatory.
Please note that this is true for the low level documentation such as
class specifications, APIs, etc. High level documentation are another
topic all together, and I think, Apple is doing very well on this front.
Books like "Inside MacOSX: System overview" are really very helpful. As
a WO trainer, I can also be only thankful to Apple for their high
quality student's manuals.
On Friday, August 24, 2001, at 01:50 PM, Ken Tabb wrote:
So while I think headers are useful, they shouldn't *have* to be the
place to go. As the previous lister mentioned, that we have to use
header
files as sources of documentation only goes to highlight how incomplete
the 'official' documentation is. And that Apple is half way (you can
decide whether or not I'm being generous by saying 'half'!) towards
providing 'offficial' (eg. HTML / PDF based) documentation, says that
Apple too does not expect us to have to go sifting through the headers.
Georg Tuparev
Tuparev Technologies
Klipper 13
1186 VR Amstelveen
The Netherlands
Mobile: +31-6-55798196