Apple’s documentation just sucks. Sure, there’s a whole hell of a lot to document, but that doesn’t excuse piss-poor documentation. Some people seem to think Apple’s documentation blows because it’s not enjoyable to read. For instance:
Let me start off by saying that I know at some level, technical documentation has to be a little explicit. With that in mind, however, I have to complain that a large portion of the programming guide reads just like this — very dry and extremely bad at maintaining the reader’s attention.
Later on in that post, Matt James describes a part of the documentation that was ‘well-written’:
This paragraph actually maintained my attention, but why? Then it clicked — it was a story!
I’m afraid that’s not what makes well-written documentation, Matt. Well-written documentation is that which provides the reader with the tools they need to do a job. At a bare minimum, documentation must first do this in order to be complete. Then, and only then, can additional perks (like ‘telling stories’) advance said documentation into the realms of well-writtenness. In other words, you can tell me all the nice stories you want, titillate my imagination with a world of fantasy and wonder and awe me with your masterful narrative, but if your documentation doesn’t tell me what I need to know in order to use your product, then it’s shit–end of story, as it were.
This is why Apple’s documentation sucks. There are plenty of places where things are altogether undocumented. What has really irked me lately, however, is when Apple decides that you don’t know best, and just won’t tell you what you want to know. For instance, I need to build some
NSTableViews programmatically in a Cocoa application. The Table View Programming Guide is sparse enough as it is, but when it comes to building an
NSTableView programmatically, this is where Apple stops:
Table views are best created in Interface Builder. They consist of a number of individual classes that are combined in a form that makes programmatic creation far more complicated than many data views.
Now, I may be hypersensitive, but here’s how I read that: ‘Table views are best created in Interface Builder. They consist of a number of individual classes that are combined in a form that makes programmatic creation far more complicated than many data views. Frankly, you’re probably not capable of understanding the way these classes are organised, so stick to the neat little GUI UI builder we made.’ My issue here is that this seems to be more indicative of Apple’s attitude toward the outside world (developers and users alike) as a whole: ‘You guys couldn’t do it better any other way, so you really should do it our way, and most of the time, we’ll force you to do so. If you don’t like it, piss off.’
I’ve pieced together how to put these classes together programmatically, and it’s dead simple. Why the writers of this guide couldn’t take the two minutes it would’ve taken to do so is absolutely beyond me. But, even something this simple is apparently far too much to expect from Apple:
NSScrollView *scrollView = [[NSScrollView alloc] initWithFrame:[self.window.contentView bounds]];
NSTableView *tableView = [[NSTableView alloc] initWithFrame:[scrollView bounds]];
tableView.delegate = self;
tableView.dataSource = self;
NSTableColumn *columnOne = [[NSTableColumn alloc] initWithIdentifier:@"columnOne"];