Blog

Introducing RubyDocs - Fast and searchable Ruby and Rails docs

Update June 1 2014: RubyDocs is now mentioned as reference documentation on the official Ruby website (look for "Ruby & Rails Searchable API Docs")!

Update May 25 2014: The source code for RubyDocs is now open source under the MIT license and available on Github. If you have any ideas for new features or run into any bugs while using RubyDocs, please open an issue!

RubyDocs was already launched at the end of 2013 but a few days ago I added the most-asked-for missing feature (being able to generate docs for just Ruby or Rails) and noticed that I have never officially introduced the project in a blog post, so here we go.

TL;DR

  • RubyDocs allows to you to generate sdoc docs for any version of Ruby or Rails (or both combined).
  • sdoc is awesome! (it also powers the official Rails API docs)
  • railsapi.com, which used to let you create sdoc docs, has been defunkt for a long time now, which is why I set out to build a replacement.
  • Does anyone know Vladimir Kolesnikov? He owns railsapi.com and I tried to get in touch with him to ask him to forward railsapi.com to rubydocs.org but didn't get an answer.

The need for easily accessible documentation

Every programmer knows the expression (and hopefully the feeling of) "getting into the zone". It's a magical condition in which you are completely focused on the problem or project at hand and are not disturbed by any outside influence. Your mind is fully occupied with keeping the project you are working on "alive" in your head, you work on one thing and already plan the next one, quickly jot down ideas about how to improve your code later on etc. Hours can pass by like minutes and when it's over you can feel mentally exhausted but incredibly happy about what you accomplished while in the zone. Kind of like Michelangelo felt, looking up at the ceiling after a long day in the Sistine Chapel. (let's hope some of our works will be as impressive as his)

One essential condition to getting into the zone and staying there is to not be interruped by anything "from the outside", be it a coworker, phone call, or chat message. This image pretty much sums it up perfectly.

The interesting thing is, you can interrupt your work voluntarily for a short time, e.g. go to the kitchen to get a coffee or visit the loo, and not leave "the zone", even sometimes coming back to the computer with fresh ideas, but if it's an outside interruption, the mental scaffold you have been building inside your head for the last 3 hours can collapse in a single second.

So when you're in the zone, you tend to only work with a few tools: your text editor (or IDE), the browser and maybe the command line. The fewer the better. But there comes a time when you have to leave these familiar and intimate grounds: when you need to find out how a method works or what that darn syntax for strftime was again. You need to have a look at the docs. For the ones of you who have docs built into their IDE (and those actually answer your questions most of the time) good for you! Everyone else runs the risk of falling out of the zone, because they have to go to Google, think about how to formulate their question, wade through several StackOverflow posts and much less useful pages to finally find the answer.

You see where I'm getting at?

Quick and easy access to documentation is essential for staying in the zone!

RubyDocs is a no-frills way to get to exactly the Ruby or Rails docs you need with as little distraction as possible. I hope you find it as useful as I do!

Discuss this post on Hacker News

Ideas? Constructive criticism? Think I'm stupid? Let me know in the comments!