How to Keep Rails Questions From Killing Your Productivity

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’s a documentation site that replaces that speed with detail and community.

APIDock

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.

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 APIDock first, especially if you’re searching for an API in an older Rails app.

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.