Why Apple’s documentation sucks…

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:

Just sayin’…

undefined method `visit’ for #<Cucumber::Rails::World:…> (NoMethodError)

I had the most obnoxious time troubleshooting this…advice varied wildly around the Internets. These were the applicable bits of my environment for my latest Ruby on Rails work (using Ruby 1.9.2p0 (2010-08-18 revision 29036) [x86_64-darwin10.4.0]):

I’d seen several other people had this same problem. Several of them solved the problem by changing the following in env.rb from:

to:

This didn’t work for me, and I beat my head against the wall for hours trying to fix the problem. I finally created a new gemset, and rebuilt from scratch. This changed nothing. Then, I found this page. His instructions include a lot of unnecessary and outdated gems, though. So, followed his directions loosely–again with a fresh gemset–and did the following:

Reinstalled the latest Rails build:

Updated my Gemfile to:

Installed the bundled gems:

Checked what versions my dice roll had landed me with:

And got:

Finally, I installed autotest and friends:

And, voilá! I now have a fully-functional BDD development system again. The key? capybara. It seems that webrat just doesn’t play nicely with the latest Rails. Capybara is intended to be a drop-in replacement for webrat, and that it certainly is. BDD-away!

UPDATE: It seems that, as of 2.0.0.beta.20, RSpec and friends still require webrat (or need other configuring to work with Capybara–for which I don’t have time). Just add it to your Gemfile, bundle install, and away you go…