What are these docs?

The Missing Cocoa Docs are intended to supplement documentation that Apple has provided. While I'm relatively new to Cocoa (migrating away from C/C++ implementations using Carbon and the old Toolbox), the past months of Cocoa development have been filled with countless hours of frustration resulting from a lack of good documentation. I've purchased and read through some excellent introductory books like Cocoa Programming for Mac OS X by Aaron Hillegass, but they too skipped over some of the important basics and left me starving for more details. Scott Anguish, Erik Buck and Don Yacktman (all veterans on the mailing lists) have now published the excellent Cocoa Programming which has helped fill in a lot of the missing information.

These docs are intended to supplement Apple's Docs because it is simply not reasonable to try and replace whole sections of the Cocoa documentation. Apple's docs are very good as API references, even though they have numerous scattered errors and are still lacking several sections of information (numerous "description forthcoming" entries still exist). There are a variety of good 3rd party books available and new ones are on the way, but unless they cover the specifics that we cover here, these docs will probably also serve as a supplement to them. Since we are not trying to replace any other docs, we will typically focus only on specific areas or aspects of Cocoa.

What aren't these docs?

These docs are not intended to help you build another text editor. Mac users already have a couple hundred text editors to choose from and we really don't need another one, so I don't want to see anyone write another one (if you want a feature that they don't have, write to the authors and request that they add it). These docs are also not designed to help you write another image viewer. We have a couple hundred of those too, so the same intention applies.

The Missing Cocoa Docs are intended to help you implement certain basic functionality and to teach you how to implement some of the more unique technologies like OS X's superb glyph and type handling. For example, they won't teach using NSViews because there are plenty of tutorials on NSViews and drawRect: methods, but there is little on NSLayoutManagers and accessing font outlines, a technique that is needed for more sophisticated graphics apps. Because bergdesign has a focus on graphics applications, our topics will likely be weighted toward graphics and type.

Author's Comments & Rants

If any of my comments make it sound as though I'm a little hacked at the Apple Docs, then my comments are probably coming across correctly. I have always believed that the original Inside Mac series was excellent documentation. It was comprehensive, but it started each topic with introductory material that was enough to get any developer going with out having to go anywhere else for information. It offered concise and detailed examples and the information progressed form the introductory material to the nitty-gritty as you advanced through the topics. But those times have changed.

The Inside Mac series degraded with time as the Toolbox grew in size and we progressed from System 7 to Mac OS 8 and 9. It became more of an API reference set and less of an instructional tool, ignoring many of the anomalies that occurred as new technologies were shoe-horned into the old system, such as the Appearance Manager that tried to coexist with the old Dialog Manager. And even though NextStep is something like 14 years old now, the docs are still little more than an API reference that is riddled with errors and missing so many needed examples.

From reading the mailing lists, most of the Cocoa veterans believe that Cocoa is very clear and straightforward. As I progress with Cocoa, I am coming to the same conclusion. But it has not been easy starting out. Coming from a background of procedural programming and brewing my own C++ objects to make life easier, I always knew what my objects were doing and when they were doing it. In Cocoa, much of its functionality is hidden and the docs don't clearly reveal all of its hidden behaviors and timing. As a result, I am not always sure what objects to use and how to connect them. And even though many Cocoa veterans believe that digging through sample code is sufficient to solve the worlds problems, it doesn't reveal the behaviors that the frameworks hide and it's certainly no replacement for clear descriptions and concise code fragments.

What finally irked me and got me started writing this was putting the finishing touches on an app and not being able to find a concise description of how to implement a couple of the most basic pieces of a good Cocoa app - an about box and help files. Apple is supposedly so fond of the user experience. But, you sure couldn't tell this from the amount of effort they put into making sure every developer could at least provide basic help.

Some miscellaneous rants:

• Why are the release notes not linked into the sections to which they pertain? Why are they in a completely separate section that is so easy to overlook?
• Each API should have a reference to the system version in which it was introduced and the system in which it was last implemented, if it is now obsolete or deprecated. This kind of info is already in the release notes. Now put it where it belongs.
• I feel like developers should be able to append to the Apple docs, kind of like a commentary section. No, the mailing lists are not the same thing. They're in a different spot, not indexed well at all by Apple (but threaded nicely by cocoa.mamasam.com), and are too difficult to search and use because the subjects don't always properly reflect the topics under them. A user should be able to find any and all documentation linked right from where it is relevant. That means from the Apple docs. It's hypertext for heaven sakes. Let's take advantage of it.

Reader Comments

If you find something that's incorrect or want to add some information, please write me at cocoadocs@bergdesign.com with your comments. While I don't want to expand some of these topics too much further, I don't want any errors or omissions to go uncorrected.