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?
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:
Download the docsets for the libraries you use.
concatmethod you actually mean.
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?
- When you have a question about an API, use a hotkey to quickly bring up Dash or Zeal.
- If you need more detail, go to the web. Try Omniref first, except:
- 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.