Friday, March 04, 2005

Cocoa Documentation Gripes

I have gripes about the Cocoa developer docs.

I very much preferred the way the old NeXT docs were structured. The documentation for a class was pretty much all in one file. NSView was documented in NSView.rtf. It included all the information about the methods (as the Cocoa class docs do now) but it also contained a great deal of information about using NSView.

With the Cocoa docs, Apple has largely moved that kind of information out, into the "Programming Topics".

I don't find this to be an improvement, for a number of reasons.

1. First, it used to be possible to print a class' documentation by just printing the single reference file. You could print out NSView.rtf, and get a useful self-contained reference document, which was largely complete. Now, if you print out NSView.html, you're missing lots of information, because that information is over in the Programming Topics. Worse, that information is split up over a number of pages. And it's mixed in with information about other classes.

2. That's my second complaint. The topics cover multiple classes, so the developer seeking information about a given class has to read through a many-page document winnowing out information on the class of interest. Admittedly, Apple's approach has advantages for learning about classes that work together. But it's a definite negative when you want information about a specific class, not high-level information. Which leads to the next gripe:

3. Sometimes, you are sent to the Topics for more information, and there isn't any. Take for example NSText.html. It sends you to the Topics about the Text system, but NSText never receives more than a sentence or two, often mentioned in passing without conveying any significant information about the class.

Likewise NSArrayController.html sends you to the Topics about Bindings, but NSArrayController is hardly mentioned. NSArrayController.html doesn't say much apart from the method descriptions, so there's very little information about the class available.

And it's extra aggravating that you've had to read through a multi-page book to discover the lack of information.

4. It bothers me when a page in the Topics is very brief. If it's just a paragraph, why not put it on a page with other things. When I click on a link in the TOC for a topic, and I get a sentence or two, it's frankly a bit of a disappointment.

I would like Apple to start putting more class-specific information in the class documentation files themselves, rather than putting it all in the Topics. I would like Apple to put more class-specific information in large contiguous chunks, so that the reader need not read through a number of pages that discuss several classes.

I have a final complaint. I find the organization of the "reference library" to be a bit aggravating. It seems like it would be better suited for an online bookstore, visited occasionally. It does not seem to be as well designed to be an intensively used reference. A more efficient, less wordy interface might be nice. The Topics descriptions, such as "Programming interfaces for representing and manipulating various types of data." are actually a bit ambiguous.

It would be nice if there were a view on the Reference Library which just described a Topic by the classes or APIs or Header files discussed within it.

Someone oughtta make...

Someone oughtta make a box which would fit over the top of a Mac Mini, and would make it look like a little tiny NeXTStation.

That'd be pretty cool, in a geeky way. If I had $500+ for the Mini, and the appropriate equipment for creating a mold and casting the case, I'd be all over it.

Then again, polymer clay would probably work well, if put on a sheetmetal core for support.