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: Brian Hook <email@hidden>
- Date: Fri, 09 Nov 2001 12:55:16 -0800
- Organization: Pyrogon, Inc.
>
1) People seemingly refuse to look at the super class's documentation
I don't think "refuse" is necessarily the right way to put it.
Sometimes there's an expectation that relevant documentation exists in a
class' docs, and percolating up through the hiearchy -- especially with
documentation as badly organized as the current dev docs -- is difficult
and error prone.
>
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.
Yes. I have NO problems searching for help using MSDN. If I need to
know how to change a cursor or set a window's focus, I can just type
that into MSDN (it's even on-line -- msdn.microsoft.com) and find it,
including docs, technical articals, sample source code, etc.
>
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.
Once again I take issue with the tone implied by "refuse". Learning
something as complex as Cocoa by basically reading a bunch of isolated
class documentation and with little or no context into "the big picture"
is difficult. It's like trying to learn how a car works by studying
each piece and guessing how they fit together.
I've practically given up on the Apple docs because of the plethora of
"Description forthcoming" stubs. It's ridiculous.
Cocoa is light years easier to use than MFC, yet I can find docs on
Win32/MFC much faster, and it's not because of any familiarity on my
part. It's just that MS provides better docs and search tools.
>
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.
To some degree this is true, but once again, it's not a refusal, it's
that there's such a shock to the system with how things are done
differently that it's very difficult to adjust. You learn a whole new
vocabulary, and for the terms that overlap there are subtle changes in
meaning.
Once again, documentation would help. If someone wrote a 5 page "Cocoa
for MFC/C++ Programmers", 90% of those types of questions could be
answered with a URL. Just like 90% of beginning "How do I write a Cocoa
program" questions can be answered with a URL to Vermont Recipes or
Learning Cocoa.
>
I see several solutions:
>
For 1), Apple could include every method from every
>
superclass in the documentation for every class.
How about just better documentation, period?
>
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.
Yes.
>
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.
Then tell them as much. A lot of newbies don't even know that book
exists. If they did, they wouldn't be newbies =)
>
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.
Don't confuse difficulty with refusal. Changing our brain from
operating in the warped, screwy MFC/C++ universe to the beautiful,
sensible Cocoa/Obj-C is not trivial for many programmers, especially
those that come from a background using static languages.
Brian