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 :).

Tagged with: , , , ,
Posted in Development, Rants
10 comments on “Ruby Documentation Sucks
  1. Jon says:

    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.

  2. Max says:

    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?!

    • DJ Bri T says:

      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.

  3. Mike says:

    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.

    • DJ Bri T says:

      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.

  4. Mike says:

    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.

  5. karatedog says:

    Ha! Never thought that a google search will yield exact result to “Ruby documentation sucks” :-)
    It is almost the year 2011, and Ruby core still sucks.

  6. Joel says:

    Lol, amen to everyone.

    Here’s what I discovered this weekend
    - In the standard library, in IO/wait. From what I’m able to tell, the first method,”nread”, doesn’t even exist for the Windows implementation of the interpreter. I can see the other methods from that class, but this one literally is not there. No mention of this in the API.

    - The second method, “ready”, does exist but is WRONGLY implemented — I dont even think its a bug. It ALWAYS returns false, no matter what, like the implementer just got lazy. I just can’t understand that…either implement it, or at least put a note in the API, or at least throw an error when its called that says “WARNING: not implemented on your OS!”. Took me hours to figure this out. Tell me, Matz, how exactly does this fit in with the Principle of Least Surprise?

    - The doc for the primary IO class has no references to IO/wait or Open3, both of which are also part of the standard library and are essentially extensions of the primary IO class which are very valuable.

    - The doc for IO.select just contains a link to the doc for Kernel.select. The doc for Kernel.select just contains a link to the doc for Kernel.select. That’s right, it has a link to itself, lmao.

    - All links in the API seem to be done somewhat mechanically, rather than being done by humans. So the definition for IO.read_nonblock says it works by “using the read(2) system call”. The “read” part of read(2) is a link to IO.read, which is a blocking read that takes N bytes. So if you interpret the documentation literally, it defines IO.read_nonblock as a blocking read of 2 bytes. If you’re someone who happens to know UNIX system calls, you might recognize the typo. But this kind of bullshit is rampant throughout the documentation, and I feel bad for the confused kid who’s trying to pick up his first programming language, ruby, and is completely lost.

    And if I want to edit the docs myself, the only thing I can find is this BS about how I have to access their subversion repository and modify the source code. To fix a typo? A simple “corrections” submission form would be too difficult because…?

    I’m only angry because I genuinely LIKE the language. The OO features, the basic data structures, even little things like ruby’s equivalent of a Switch statement are very expressive, well-abstracted, and beautiful. But once I start dealing with anything system-related I feel like I’m using poorly-documented C functions. The language is bloody 15 years old and they still can’t be bothered to make it accessible. Or maybe its just my fault and I’m the idiot for not learning Japanese!

    >_<
    Waaaaaaaaaaaaaaaaaaa

  7. qwerty says:

    Yes, the docs should and could be better. No argument there.

    However, the API is not the language. Not at all. You don’t have to use any of those 108 libraries to use Ruby.

    If you understand network programming, the constants in the socket library should be self-evident. See where I am going here?

  8. Kashif says:

    I just dumped Ruby after fighting with it for 6 months on/off. It’s not just Ruby’s documentation that sucks. All other popular libraries also _suck_ such as eventmachine, Thin, and Rack. My co-worker also agrees with me…

    I spent all my time trying to figure out ‘how to do things’. Once I figured it out, it was great…and elegant…but what’s the point, there was too much magic at times to figure out what was happening.

    A language can be pretty, but it’s the libraries that make it useful and practical.

    I learned an important lesson: judge technology by documentation, not by the fact it is sexy or elegant.

Leave a Reply