The other day one of my team members was complaining about the lack of documentation in Ruby on Rails. I had to think for a minute because I never had problems finding information I needed. It finally occurred to me that the ruby development and documentation cycle is very different than Java's.

First of all, ruby code *is* documentation. The constructs, conventions and style used in ruby (e.g. the unless construct, and underscores in verbose method names) make the code more descriptive. The code is readable. Evidence of that is found in rdoc, which is ruby's JavaDoc equivalent. The actual code is embedded directly into the rdoc pages, as if it were part of the description.... because it is!

Ruby also attracts a different crowd (at least for now). Ruby developers enjoy riding at the forefront of the technology wave. This makes them more likely to have blogs. And they use those blogs to document code recipes, successes, etc. Those blogs get absorbed into the ethos, indexed by the engines, and reiterated by the rest of the blogosphere like a big echo chamber. Consequently, the blogosphere is the biggest ruby manual and how-to in existence.

Now, that suits some, but not everyone. Despite the readability of the code, and the mass of the "documentation" on the web, I completely understood what my friend was getting at. There are very few ruby "specifications" that you can download, read, and process in their entirety.

One could argue that the success of Java is in (a large?) part due to the success of the Java Community Process (JCP). You may dispute the quality of the APIs themselves, but the JSRs fill a real need. The specifications coming out of the JCP give individuals and enterprises a firm fixed interface on which to hang their hats.

To my knowledge, Ruby has no such organization. Without it, when developing a ruby application, you are left praying you stumbled upon the right blog post, at the right time, with the right solution.

The importance of community accepted interfaces becomes even more important when considering pluggability, and solution portability. Recently, I ran into the need for HTTP Digest authentication in Rails App. I found lots of proposed solutions, and a ton of authentication plugins, gems and modules, but none of them were swappable, and not one of them offered me a "standard" means of achieving digest authentication. In Java, I could have gone to the JCP, found a suitable interface, examined the vendors that passed the TCK tests, and gone about my business knowing (at least in part) that the interface I was about to use had some consensus and support behind it.

Alas, I love Ruby. I love Rails. They are a joy to program in. And for that reason, I'm entirely okay with the "faith factor" required in pulling down random solutions from blogs. Hell, if the solution doesn't work, it will be fun to fix it. And that is fine for the beer review site I put together, but that is (arguably =) not a mission critical application. I'm not sure businesses can assume the same risk.

I'm not foolish enough to believe the JCP is flawless (e.g. Entity Beans anyone?), but businesses can't always afford to bet the farm (or their investor's farms) on solutions not backed by real consensus organizations. I understand slow consensus processes run counter to everything Ruby on Rails stands for, but perhaps the Ruby Community Process can offer a more agile environment basing specifications on code and capability, not politics and vendor positioning. (which IMHO is the thorn in the side of the JCP)

just some more food for thought,
bone