Ruby Documentation Sucks

Okay, this is going up a day late. My bad. I’ve been busy. Regardless, I have a rant which any programmer can sympathize with.

I’ve been recently programming a proxy in the Ruby programming language, which is known for its code elegance. When you know how to use it, it’s a great language. The problem, however, comes when to learning about the API in the language. To put it bluntly, the documentation is crap. To be more specific, a good amount of it is incomplete, and those sections that are completed fail to follow a consistent fashion. To put things in perspective, there are 108 core libraries included in the Ruby documentation; over half of those libraries have incomplete documentation.

Now, this isn’t that much of an issue if you know how to use the language; after all, there’s no need to go to the documentation when you know the language. The problem comes when you are like me, learning how to use the language, and don’t know what any of the constants for the sockets library do, which is a bit of a problem when you need to program a proxy. See where I’m going with this?

Maybe I’m complaining because I’ve been spoiled on PHP‘s phenomenal documentation, which is an amazing feat when it comes to documentation. All of the functions are properly laid out with plenty of cross-references, and tell you exactly what to expect for each and every function. The documentation is a work of art, I kid you not. Don’t believe me? Try learning how to do something complex in PHP using the documentation only, then try to do the same in Ruby.

I have heard some people make the argument that Ruby is open source and relies on its members to do the documentation, hence the lack of it. While I understand this argument, it doesn’t entirely make sense. Ruby has a large band of dedicated followers (think Jehovah’s Witnesses-style) who should have filled in the 1.9 documentation by now. Thinking about it from another perspective, PHP is a free and open source language as well, and look at the detail in there compared to Ruby.

All I’m saying is that Ruby needs to step up its game a bit, otherwise it will have trouble competing for those people looking at learning a new language. If it wasn’t for an amazing IBM document on Ruby socket programming, I would have moved on to another language by now.

Anyways, tune in this Friday for something different. I realize programming isn’t everybody’s cup of tea, so I’m hoping to branch off into something a little different for those of you who either find computers boring, or those of you that simply don’t understand them. As always, I appreciate you reading, and I appreciate even more those of you who tell a friend about my blog :).