bad documentation
bad documentation
- Subject: bad documentation
- From: email@hidden
- Date: Tue, 13 Nov 2001 00:13:22 +0100
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.