Re: Docs
Re: Docs
- Subject: Re: Docs
- From: Jonathan Hendry <email@hidden>
- Date: Wed, 22 Aug 2001 19:35:04 -0500
On Wednesday, August 22, 2001, at 06:19 , Stuppel, Searle @ San
Diego Central wrote:
as i was saying in some other email to Ondra, "interpret" and
"scan" would
be the last words i would think of searching for when i am looking
for a
function to remove URL's out of a NSString.
Besides, if cocoa is supposed to come with documentation, shouldnt that
documentation be accurate and informative? instead of sketchy and
vague? Not
to be sarcastic, but is that really too much to ask? or expect?
The documentation is quite good in spots, and lacking in other places.
What you're seeing is the result of massive changes, and the fact
that the system is a bit of a moving target.
The docs that cover older OpenStep material tend to be pretty good.
When you add in new functionality, like Cocoa support for OpenGL or
QuickTime, that's new and hasn't been covered yet. For that matter,
the relevant Cocoa APIs probably aren't final yet anyway.
Areas where Cocoa doesn't support something and Carbon or
other APIs have to be used, those dependencies aren't well
documented either. I chalk those up to time and a moving target.
We just wish apple gave a damn about its documentation. To say
it's attitude
towards it is poor is an understatement. OSX has been out long
enough for it
to have been done RIGHT.
Not really. Good documentation isn't easy, especially when there's
such a _huge_
amount to cover.
Admittedly I am a novice programmer, but I feel so alienated by
the poor
docuemntation of osX, that I struggle to see why I would continue
attempting
to develop for it. I am not stupid. I can read and learn and
figure things
out. But somehow osX mytifies me like nothing else.
Do you have an example of good Apple documentation, which you'd
like to see Cocoa emulate?
A significant problem is just being able to access the docs in a
convenient
way. HelpViewer doesn't work for the purpose. In ProjectBuilder, the
default templates hide framework headers and documentation
way, way, way down deep. I can imagine people unfamiliar with
frameworks being unaware that there's even any documentation
_there_.
I've modified my Cocoa/ObjC project templates so that the AppKit
and Foundation headers and docs are grouped near the root of
the project hierarchy. I find it much easier to use.
I could put my templates on iTools, if anyone's interested?
Otherwise, I use 'open quickly' to get at header files (but then, I
know which ones I want to see already). I'm also using MTLibrarian,
and OmniWeb to view the HTML docs.