Apr 14, 2008 — by
Mikael Roos

Ruby on Rails documentation sucks. Somehow the convention over configuration idiom translated into intuition over information. It’s not easy to learn Ruby on Rails with the API documentation on your screen and a glimmering pin-up photo of David in your hand. If you are a Rails beginner, you know exactly what I’m talking about. If you’re a Rails veteran, you might have to think back a little: remember when you saw that dynamic scaffolding screencast and dug head first into the new, forever changed world of web development? All those amazing innovations amidst all those inexplicablehash parameters with such descriptive names as options or args.

The bad API documentation was never just bad for the Rails community. First of all it garnered some really good books. A lot of writers wanted to be the first to write that Rails and Ruby bible. These were ambitious, excited writers, which is a hell of a lot better than your average commissioned Joe writing about Symbian or Spring or something.

Secondly, the lack of a good API documentation created a lot of frustration in the beginners’ minds and every single Rails beginner who plowed through that struggle also went through the period of releasing that frustration. I’m talking about those moments when they relied on that convention (and intuition) and felt the hand of David guiding them and, on a mere hunch, wrote something they had never seen anywhere, and it worked – it actually friggin’ worked. Those moments made these people hard core Rails fanatics who never looked back.

Well, the buzz is over and it’s time for a reality check: rails documentation sucks. It still sucks! And it’s not getting better. So we at Nodeta decided to do something about it. It’s time to truly harness the power of the community to improve the documentation. In the age of Rails, that can only mean one thing: a killer app. That’s why we are whipping up a summer project of our own, to create Rails-Doc, the community driven Rails documentation app. The idea came already almost a year ago and the final decision was made a couple of months ago. Since the idea emerged, we have been blessed with some competition and an amazing starting point. Most plans have already been made: the project will start in mid-May and the first release will be out by the end of June. Stay tuned for updates on Rails-Doc.