Practicing Rails is out! Get it for 25% off until Friday, February 13th.

While you write code, questions pop into your head constantly: How do I call this method? What options does it take? What happens if I pass an object instead of a number?

These questions destroy your productivity. When you don’t know the answer right away, you forget what you were doing. You get yanked out of your flow, and it takes a half hour to get back to where you left off.

So how do you find the answers you need without slowing down?

Fast lookup

Speed is key when you look up API documentation. You want to get your answer and get out as quickly as possible. Otherwise, it’s way too easy to get off-track. I can’t count how often I’ve needed to know the parameters to a method and somehow ended up looking at embarrassing text messages on reddit for an hour.

For speedy documentation, you’ll want Dash, for Mac, or Zeal, for everything else. With these tools, you can hit two keys on your keyboard and bring up the docs you need without having to think about what you’re doing.

But they need a tiny bit of setup first.

Once you download either of these apps, do these two things:

  1. Download the docsets for the libraries you use.

    I grab docs for Ruby, Rails, CSS, HTML, and Javascript, and that’s about it. If there’s a complicated gem you use a lot, like Nokogiri, grab those docs too. But don’t go overboard – if you have too many docs, you’ll slow down as you try to figure out which concat method you actually mean.

  2. Set up the Global Search Shortcut. On the Mac, I usually use option-Space.

    This is what transforms Dash from “just another doc site” into a totally essential tool. Once you set up the global search shortcut, you can hit option-Space, start typing, see the docs you need, hit option-Space again, and have your answer without even realizing what you just did. You can answer your API questions before you knew you had them.

Details, questions, and comments

Unfortunately, sometimes the API docs don’t have all the details you want to know. Or you might need to know how a feature works on the inside.

You’ll have to sacrifice speed to answer these questions. But there are two documentation sites that replace that speed with detail and community.


APIDock only covers Ruby, Rails, and RSpec. But it’s still helpful:

  • APIDock will tell you when Rails methods were deprecated, and what you should be using instead. It keeps track of version-to-version changes in Rails all the way back to 1.0. So if you’re working with legacy Rails code, it’s an incredible resource.

  • Lots of API methods have comments, contributed by Rails developers. The comments are really good. With APIDock, you’ll hear about edge cases and common problems before you run into them.


Omniref is new, and has some neat ideas. It has API docs, just like Dash and APIDock. But it also has StackOverflow-like Q&A on the methods, classes, or gems you’re looking at. And when that doesn’t solve your problem, you can see the source code right next to the docs.

This is a great way to get familiar with Rails and gem internals. If the documentation doesn’t answer your question, you can go straight to the source. And once you figure it out, you can leave a note right in the code for the next person to come along.

Your new documentation workflow

So, how do you put all this together?

  1. When you have a question about an API, use a hotkey to quickly bring up Dash or Zeal.
  2. If you need more detail, go to the web. Try Omniref first, except:
  3. If you’re searching for an API in an older Rails app, use APIDock.

When you can instantly find documentation, it’ll transform your Rails productivity. You’ll not only stay more focused, you’ll learn even more about the libraries and frameworks you depend on.

You can’t know everything about every tool you use. You’ll always rely on documentation at some level. So spend a little time now to save time when you look things up. It’ll pay off massively through your entire programming career.

Did you like this post? You should read these:

Finished another Rails tutorial and still don’t know how to start?

Have you slogged through the same guide three times and still can't retain enough to write apps on your own?

In my free 7-part course, you’ll discover the fastest way to learn and remember new Rails ideas, so you can use them when you need them. And you'll learn to use what you already know to build your own Rails project.