Ruby Documentation Sucks
- September 22nd, 2009
- Posted in Development . Rants
- Write comment
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 
.
Hey Brian, why not use like, Visual Basic or Java? I heard they work really really well!
… Yes, I was being sarcastic. Sad to hear Ruby has such poor documentation, I was motivated to learn it soon. If you find the time, contribute to it yourself, so the next guy doesn’t need to find some obscure IBM paper.
I completely agree with you, Ruby doc is crap! I’ve been asked to automate server api testing with Ruby but it takes so much time just to find whether I can do whatever I need with Ruby. And when I do find the feature I need, there’s no freaking description of what the function returns or takes as parameters unless you go through the code.
I really enjoy Java docs, the description is so well put together. Why wouldn’t everybody follow that standard?!
Yes, Java docs are put together much better than Ruby’s docs are. What I ended up doing for Rails is I went out and bought a book. It was the best $50 I’ve ever spent, and I highly recommend dropping a bit of cash to pick up a good, comprehensive textbook that will hopefully last you many years.
I have just started looking into using Ruby as an alternative to PHP. I’ve been using PHP for years, and although I really like it, I had heard that Ruby might help speed up some of my development work.
I started by getting an overview of the language itself, which I quite like. I then moved on to looking how I would implement things that I have already implemented in PHP. Take, for example, symmetric encryption. There’s apparantly an MCrypt library, and an OpenSSL library for Ruby, but the documentation is astoundingly bad. After half an hour of searching, I could only find a few examples. The ruby-doc.org section on OpenSSL is pretty much empty. Compare this with the PHP documentation, and the difference is obvious.
As much as I would like to learn and use Ruby, it won’t speed up my development if I can’t access decent documentation.
One would think that a language that has been around for that long would have developed decent documentation and examples at this point. Yes, for some of the common problems there are many examples to be found, but for some of the more complex stuff — the things that you would need examples for — the resources simply don’t exist yet. After being spoiled on PHP documentation for so many years, the Rails documentation is painful at best to work with. I’ve found that getting books is your best bet, along-side some serious experimentation. “Advanced Rails Recipes” is another good book along with the one I mention in the blog post.
I have plans in the works to create a development site on which I’ll be posting a bunch of programming tips and tricks that I’ve learned over the many years I’ve been programming. More specifically, I’ll probably personally focus on Rails due to the lack of good documentation, but there’s certainly room for others to help with other languages.
I know this is quite an old post now, but since writing my last comment, I have been looking into other web development frameworks. I have, after much investigation, experimentation and deliberation, opted for Catalyst. It’s a perl framework, and I love it. It wasn’t easy to learn, but the online documentation is very good. I also bought The Definitive Guide to Catalyst – a book which I cannot recommend highly enough. I am slowly but surely becoming a perl addict.