• Open Menu Close Menu
  • Apple
  • Shopping Bag
  • Apple
  • Mac
  • iPad
  • iPhone
  • Watch
  • TV
  • Music
  • Support
  • Search apple.com
  • Shopping Bag

Lists

Open Menu Close Menu
  • Terms and Conditions
  • Lists hosted on this site
  • Email the Postmaster
  • Tips for posting to public mailing lists
Re: bad documentation
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


  • Follow-Ups:
    • Re: bad documentation
      • From: Angela Brett <email@hidden>
References: 
 >bad documentation (From: email@hidden)

  • Prev by Date: Re: New Cocoa Programmer
  • Next by Date: Re: All these newbie questions that are answered by documentation
  • Previous by thread: Re: bad documentation
  • Next by thread: Re: bad documentation
  • Index(es):
    • Date
    • Thread