Coyote Tracks

PHP is a kludged-together, ugly mess of a language. But its documentation is quite superlative: practically every function has documentation written in a more-or-less standardized format, plus whatever comments users have added. In addition, they have something near and dear to my heart:

Downloadable documentation.

This means that if I’m developing on an airplane at 30,000 feet, or on a BART train in the tunnel that runs underneath San Francisco Bay, I can just use my own local copy of the docs.

I’ve long been annoyed with the state of both Ruby’s documentation and Ruby On Rails’ docs. Both of them use the awkward, quadruple-framed RDoc format that breaks up screen real estate inefficiently, makes keystroke navigation difficult if not impossible, and forces the browser to load a 600K page listing every single Rails method, even if what I really want is just the Class hierarchy listing.

But the other thing that’s annoyed me about Ruby’s and Rails’ docs for a while is that there is no downloadable version available. If I haven’t got an Internet connection available, I can’t look up the docs. End of story.

Which is a penalty I suppose I’ve learned to accept when I’m travelling. But at my home workstation, I should be able to see the docs any time I want, right?

No, not if the people maintaining the Ruby On Rails web site screw up and let their domain registration lapse. Because of their mistake, I can’t do the development I was trying to get done tonight. (So I’m writing a snarky blog entry instead.)

Always make your docs downloadable. If the Rails team had done that, I’d be coding right now, instead of trying to shame them into making their documentation usable. (Heck, I might not even have noticed their error, because I’d just have opened my own local copy instead of going to their site in the first place.)