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: Steve Bennett <email@hidden>
- Date: Fri, 09 Nov 2001 20:13:19 -0500
Rather than answer this in huge detail, two observations:
- The documentation is terrible, period. It has no overviews to speak of,
no code examples to speak of, is out of date (and just plain wrong...) in a
number of areas, makes assumptions that you already know the details of how
everything in the system works, fails to make any reference or pointers to
the information that *is* available elsewhere but is needed to understand
the topic at hand, and is completely missing a significant portion of it's
reference content.
It's certainly nowhere close to Apple's standards of documentation from the
Inside Mac days. The current Cocoa docs remind me a lot of old Windows 3.x
docs where you pretty much had to know the answer to your problem before you
could figure out where in the docs to look to find it.
Your items #1, 2, and 3 would be much resolved if we had anything close to
good documentation. (Your item #4 is a sarcastic generalization that's
probably wrong for 99% of the people posting here, and not worth responding
to...)
- This list is called "cocoa-dev". It's for people doing cocoa development,
whether they're new to the system or not. It's *not* called
"cocoa-expert-only-dev." If you feel an expert-only list is needed, go make
one somewhere, moderate it (so those pesky newbies can't get in), and stop
complaining here.
-->Steve Bennett
Erik M. Buck wrote:
>
>
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:
>
>
1) People seemingly refuse to look at the super class's 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.
>
>
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.
>
>
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.
>
>
>
I see several solutions:
>
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.
>
>
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.
>
>
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.
>
>
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.