Re: All these newbie questions that are answered by documentation
Re: All these newbie questions that are answered by documentation
- Subject: Re: All these newbie questions that are answered by documentation
- From: Rainer Brockerhoff <email@hidden>
- Date: Fri, 9 Nov 2001 20:32:14 -0200
Warning: long post! Opinions! Debatable statements! Reputations
shredded while-U-wait!! :-)
From: "Erik M. Buck" <email@hidden>
Date: Fri, 9 Nov 2001 14:31:44 -0600
It seems to me that most of the newbie questions that are easily answered by
documentation and keep recurring in this forum and others are due to 4
general causes:
As one who has asked a certain amount of easily
answered/stupid/RTFM-type questions here and on other lists during
the last 5 months or so, I'd like to make a few comments here...
I started out programming an application (XRay) in early May. I'd
never developed in Objective-C before, had never seen Cocoa, and
indeed had never used Mac OS X.
On the other hand, I had 15 year's experience of C and C++, similar
experience in other languages and OSs, and a _lot_ of practice in
picking up new languages and APIs. So what I did was set out to
program a small real-world application, which turned out to be much
larger than I anticipated...
My technique here was what I call "lazy learning", which is to load
new APIs and concepts into my mental cache only when they are
needed... sounds like good Cocoa programming practice to me, anyway
:-)
I see several solutions:
I've merged the problem list with the solutions list for better
commentability, if there is such a word.
1) People seemingly refuse to look at the super class's documentation
...
For 1), Apple could include every method from every superclass in the
documentation for every class. That would only expand the size of the
documentation by a factor of 5 or so, but then people would not have to look
in more than one place as often.
At first, it was very difficult for me to find out _what_ the
superclasses were, due to unfamiliarity with Objective-C notation,
header organization, and Help Viewer's deficiencies. Now, with the
new PB's class browser, that's very easy and it's what I first look
at.
Including the documentation would IMHO be too bulky, unless this
would mean including just the single definition line with a link to
the superclass documentation.
2) Sherlock sucks so bad that people will not use it to search the
documentation and newbies can not be bothered to use MTLibrarian or another
search tool.
...
For 2), Apple could/should just scrap the shitty Sherlock and revive Digital
Librarian or something better. People could also start using google.
Google is very handy for searching Apple's on-line documentation.
I've never used Sherlock's content indexing feature at all, even in
Classic Mac OS. I agree that Sherlock on Mac OS X is slow and
unreliable even for searching for file names :-).
Help Viewer's search - at least the dozen times I tried it in the
first week - never found anything whatsoever for me. Perhaps I don't
know how to formulate search criteria in "natural language"?
Actually, after a couple of month's experimenting, I'm getting
reasonable results using PB's framework search feature - at least it
gets me the declarations. I've just downloaded MTLibrarian, hopefully
it will work better.
Yes, Google is great - but you have to be connected to the Internet
at all times, which isn't always possible or economical.
3) There is a lack of good concepts and overview documentation. Newbies
refuse to just dive in and read the details about classes. They seem to
want broad overviews that at least tell them where to look. Combined with
the fact that newbies don't even know the terminology to use when searching,
they can not find anything.
...
For 3), more is better, but most of the newbies posting have never bothered
to read Object Oriented Programming and Objective-C. I don't know how we
can expect these people to read any kind of overview if they are not willing
to even learn the language of the frameworks.
Nothing beats some familiarity with the frameworks, of course. In the
last 2 or 3 months I usually know where to find something. But in the
beginning, it was tough.
Reading the "System Overview" manual repeatedly was a great help.
"Introduction to the Application Kit" is so short as to be of little
help. What I missed most in the latter - at least coming from a C/C++
background - was a detailed explanation of control flow in a Cocoa
application. I still haven't found a good description of that
anywhere, although I've pieced most of the puzzle together over the
months.
Lack of a mental model about control flow hampered me the most in the
first months. It took me 3 months to get a reasonable feel for what
was happening, and when. Contrast this with the 15 days it took me to
learn C++ _and_ PowerPlant some years ago! Even though PowerPlant
docs aren't _that_ much more enlightening for newbies, just
single-stepping through a simple sample application told me nearly
all I needed...
Since we don't have the Cocoa sources, and won't have them anyway
(and _having_ the PowerPlant sources of course caused me to fall into
_those_ pitfalls), single-stepping through the frameworks isn't
possible. I still haven't had time to learn gdb properly, I suppose
just breaking at every single method call _might_ be possible.
One thing which you haven't addressed is the regrettable state of the
Carbon documentation - not of the "Carbon-based application"
documentation, but of the Core Carbon interfaces, like File Manager,
Resource Manager, and so forth. I've found myself digging out my old
"Inside Mac" paper volumes (I to VI) to check on what some functions
do. I've copied a selected number of pdf's from old System 7 and 8
developer CDs to my hard drive - they're much more complete than the
newer docs.
And frankly, documentation for the BSD APIs sucks completely for
someone who's never developed for Unix. "man" pages are a joke in bad
taste. Yes, _after_ you learn how things hang together somewhat
better documentation can be found on the web. In the headers, a
paragraph before each definition, stating what it does - like in the
Carbon headers - would have saved me at least a man-month of work.
4) Familiarity with C++ and MFC has warped their minds to the point that
they just can not understand a dynamic language like Objective-C and
flexible frameworks like the Application Kit. A refusal to change mindsets
locks people out of Cocoa.
...
For 4) If people will not change and/or can not see the advantages of a
different way of doing things then I don't think Cocoa will ever appeal to
them. I suggest that we forward all such people to the Carbon lists.
The main stumbling block is the regrettable use of generic terms like
"object" to mean different things in different languages. Then again,
I agree with Edsger Dijkstra that even the use of anthropomorphic
terms like "language" and "memory" is unfortunate...
Regarding reading up on "Object-Oriented Programming", my early
experiences with that particular sequence of buzzwords in the
seventies soured me permanently on reading somebody else's catechism.
Regarding C++ mindwarp, I've also, thankfully, refused to learn more
than absolutely needed about STL and templates when I learned C++.)
I've found the Objective-C pdf's themselves quite sufficient after
the initial "culture shock".
Regarding reading up on Objective-C, I'm also amazed at the amount of
people who have never learned basic C before starting on Objective-C.
The Objective-C books don't emphasize this enough. Sincerely, I think
a "full" Objective-C book is needed, which teaches C from the
beginning and only gets into objects in the second half.
--
Rainer Brockerhoff <email@hidden>
Belo Horizonte, Brazil
"Originality is the art of concealing your sources."
http://www.brockerhoff.net/ (updated Oct. 2001)