Comments on: Ruby Documentation Sucks

By: Mike

Mike — Mon, 07 Jun 2010 18:51:18 +0000

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.

By: DJ Bri T

DJ Bri T — Mon, 23 Nov 2009 17:25:31 +0000

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.

By: Mike

Mike — Mon, 23 Nov 2009 15:49:02 +0000

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.

By: DJ Bri T

DJ Bri T — Fri, 16 Oct 2009 18:05:40 +0000

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.

By: Max

Max — Fri, 16 Oct 2009 11:05:03 +0000

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

By: Jon

Jon — Sun, 27 Sep 2009 22:23:09 +0000

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.