Re: bad documentation
Re: bad documentation
- Subject: Re: bad documentation
- From: Charles Srstka <email@hidden>
- Date: Mon, 12 Nov 2001 19:02:51 -0600
One thing that I find very helpful is the fact that the AppKit and
Foundation both have their docs in PDF format. If you open them with
Acrobat Reader, you can quickly search through all of the AppKit or all
of the Foundation, without having to use Sherlock, the Help Viewer, or a
connection to the Internet. It's very nice - you might want to try it.
On Monday, November 12, 2001, at 05:13 PM, email@hidden wrote:
Following a long discussion/rant/noise in the last few days about
beginner'
s problems, I would like to say something CONSTRUCTIVE about that. In
particular I would like to explain -- in my poor english, sorry -- to
Apple (and Erick Buck and a few others) WHY I believe the documentation
is bad. Hopefully they will find some time to improve it.
Let us start with a few general statements:
- Classes tab in PB is really a GREAT improvement, but still has a
number of problems (already detailed in this list and project-builder
list). I would like to congratulate the PB team about it.
- Sherlock is still (quite) broken in MacOS X (used to be great in OS
9) and Help Viewer is just a (bad) joke. Period.
- Searching. Used to be very bad in Apple's site; probably improved by
the Google engine. Still, you must be connected to Internet. The only
decent way to search in your hard disk is the PB 'find' panel, but only
for definitions. So improve Sherlock or Help Viewer.
- About the HTML documentation:
I usually read it using OmniWeb. Not because it's fast (it's not), but
because it has a great system to organize bookmarks. The main
inconvenient in the HTML docs is that they are NOT ORGANIZED. Examples:
-- Classes are separated in Foundation/AppKit frameworks. That just
doesn'
t make sense while programming an app. Some very useful methods for
Foundation classes are in categories in AppKit (like NSBunde for
instance)
and THERE IS NO LINK IN BETWEEN. Not only is it difficult to handle
when you already know it (you have to navigate a lot), but it's very
difficult to figure out otherwise, particularly if you learned OOP in
another language. Remember that in C++ and Java it is not possible to
add method to a class. There is a huge difference between just reading
a book explaining protocols, and really understanding their power.
>-> WE NEED an html page summarizing all Cocoa
classes/protocol/functions (an index).
-- Classes are indicated with their inheritance path, but the inherited
methods are not even mentionned. This makes difficult to understand
their behavior. It woul be sufficient to recall the name of inherited
(and non overriden) methods, with a hypertext link. As a good example
of class documantation, take a look on the java classes doc at
http://java.sun.com/
j2ee/sdk_1.3/techdocs/api/index.html
(You don't need to like java ;-)
-- At the very top of every page of the doc, there is a two links
"documentation":"cocoa". YOU CANNOT follow them, because they
correspond to a link 'help:something' that no browser understand. (Okay
there is Help Viewer; who is laughing?) Even PB cannot follow one these
link (the most useful: coca).
-- If you manage to go to the Cocoa main page, as I'm pretty sure that
most experts never do, you will find something interesting: at the
lower part of the page, there is AT LAST some organization, with the
general title "Programming Topics". Now read on, say "basic drawing"
(something simple to start on). You will get (in large characters):
Overview of Programming Topic: Basic Drawing
Description forthcoming.
Child Topics
None
Discussion
This topic is under construction.
No comment! (That's now more than one year that Mac OS X is out,
remember ?)
-- So to find useful information you MUST read the classes description.
That means that you must understand the connections between the
classes. Exercise: you want to have information on doing a
multithreaded application, where should you look? Answer: NSThread (NOT
NSTask), NSConnection (the only example, but it's incomplete) are
obvious but the most useful is NSApplication, for detachDrawingThread:)!
-- Finally I'm not the only one to say that is (still) a large number
of errors/incorrect statements in the doc. Cocoa experts should take a
look (and fill a bug report) about the doc on copyWithZone for instance
(exercise: where is this method documented?). In my opinion, the line
that starts with
Product *copy = [[Product alloc]
is just plain wrong; it should be
Product *copy = [[[self class] alloc]
...and this makes a HUGE difference when subclassing (which is the very
difficult point here).
Incidentally there is a very interesting sentence in this page:
"When a class inherits NSCopying behavior, you must consider the
possibility that the superclass's implementation uses NSCopyObject(). "
That's funny because the documentation does NEVER explain if a class
uses NSCopyObject() to copy objects.
Okay enough for today it 0:11 here in France!
Yours,
Thomas Lachand-Robert
********************** email@hidden
<< Et le chemin est long du projet ` la chose. >> Molihre, Tartuffe.
_______________________________________________
cocoa-dev mailing list
email@hidden
http://www.lists.apple.com/mailman/listinfo/cocoa-dev