Re: (long) All these newbie questions that are answered by documentation
Re: (long) All these newbie questions that are answered by documentation
- Subject: Re: (long) All these newbie questions that are answered by documentation
- From: "Erik M. Buck" <email@hidden>
- Date: Fri, 9 Nov 2001 20:07:12 -0600
I am sorry for the "tone" of my post about the 4 causes I perceive for
repeated questions in this forum that are easily answered by the available
documentation. I would not participate in this forum and answer questions
if I was not an enthusiast for Cocoa. I want to share Cocoa with everybody.
My biggest heartbreak is that Apple reneged on cross platform support and
locked 95% of the programmers out of Cocoa forever.
All of that aside, my perception of the causes and my proposed solutions
were completely serious and not intended to be snide or ironic. I seem to
be getting the most grief from two of my comments:
1) People "refuse" to look at the super class documentation and "can't be
bothered..."
2) We should direct people who just don't appreciate Cocoa to the Carbon
lists.
The available Cocoa documentation requires knowledge of object oriented
programming concepts. The concepts portion of "Object Oriented Programming
and Objective-C" is a good in many ways, but it is insufficient on its own.
However, I find it hard to believe as some have claimed that they didn't
know to look at the super class documentation. If that is true then such
people are in so far over their heads that they should not yet attempt to
use Cocoa. Regardless, a simple search for unfamiliar terms and methods
found in one document will almost certainly discover other documents
including the super class' document.
As I and others have noted, the very first link in the document for each
class is a link to its superclass. My personal opinion is that if people
know enough to consider the methods of the superclass and "can't be
bothered" to click on the very first link in each document to view the
superclass then they are clearly "refusing".
Actually, I am sympathetic. It is handy to have all of the information that
you need in one place rather than having to look in multiple documents. No,
mere links are not enough. People are not following the existing links.
That is why I quite seriously suggested including all of the documentation
for every method that an object implements including the ones that are
inherited in every class' document. Most respondents seem to think I was
being sarcastic. I was serious.
I was also completely serious that some people should be directed to Carbon.
Carbon is not evil. It is just ugly in my opinion. Everything is a matter
of opinion. People who don't appreciate Cocoa are not necessarily stupid,
they just have tastes that differ from mine. Rather than trying to change
their tastes (which is probably impossible), I think we should direct the to
something more to their liking.
I think the Cocoa documentation is pretty good! I am sure I will be flamed
for that. The "Description Forthcoming" stuff is actually very small
compared the volume of documentation, and it only applies to the newest
features of Cocoa. In fact, you can date the arrival of a feature by the
type of documentation that exists for it.
I don't think there is anything wrong with the current documentation. We
just need more documentation. We need a 500 page concepts and overview
document. If it is any shorter that it will be lambasted the way "Learning
Cocoa" was lambasted.
Most importantly, Apple has let us all down when it comes to search tools.
As many have noted, MSDN is a far superior search tool. (Too bad if
produces so much clutter that you can not find the critical information, but
that is another diatribe :)
I did not mention Apple help because it is so useless that I assumed nobody
would even consider using it.
I did mention Sherlock because it has the potential to find documentation.
I have never used Sherlock on OS-9. Maybe it is better there, but it stinks
on OS X at least when it comes to searching documentation. The irony or
tragedy is that Apple has/had Digital Librarian which was an excellent tool
for searching documentation. Apple also has/had HeaderViewer.app and
class/instance browsing integrated with gdb and many other features.
Finally, for people with always available Internet Access, Google is a
savior. A google search with the words "apple developer" and whatever terms
are of interest will do a pretty good job of fining the right documents.
In summary, forgive me if I write RTFM in many of my answers. I almost
always also provide the google search the found the answer. I don't like it
when people respond to "RTFM" by asking which "FM" because I provide the
link and the search criteria. I don't always know which "FM" and I have
been doing this for 12 years. That is why a recommend searching and why I
am frustrated with people who "cant be bothered" to search.
Oh, and as Heather Hickman reminded me while mildly chastising my "tone",
there is a new book on Cocoa programming available on Amazon.com.
http://www.amazon.com/exec/obidos/ASIN/0672322307/qid=1005357800/sr=8-3/ref=
sr_8_3_3/103-7999620-0545441
People have told me to "put up or shut up" so I "put up" with a lot of help
from my friends. However, this is NOT an introductory book. It is intended
for intermediate and advance programmers, but it does have a lot of overview
material and guidance about where to look.