You’re working with a brand new library or feature, and you just can’t understand the documentation. Maybe it’s hard to get set up, so you have to bounce between RDocs until you learn how everything fits together. Maybe the documentation doesn’t even exist. Or maybe you just learn best by seeing lots of examples.

You need some help. But where do you learn how to use a feature, if not its documentation?

One of my favorite GitHub features

When you want to go beyond the documentation and see real-world uses of a library or feature, use GitHub’s code search.

For example, say I just read the Rails guide on Conditional GET Support. I feel like I understand it, but I want to see some more examples before I use it for real.

I could hop onto GitHub search, and look for "if stale?". Then, in the sidebar, pick code and Ruby:

And now I have tons of great examples of how stale? could be used.

Not all of the examples are interesting. But in one listing, I notice the author using Post.maximum:

class ArchivesController < ApplicationController
  def index
    if stale?(last_modified: (Post.maximum(:updated_at) || EPOCH).utc, public: true)
      @months = Post.find_all_grouped_by_month

That seems like a great way to use stale?. And if I hadn’t seen this example, I might not have thought to try it.

How should you use what you find?

When you search open-source code, you get hundreds of examples for nearly any feature. You’ll notice where the documentation makes sense, and where it’s over-simplified. And you’ll see objects working together in real code. That will teach you more about how classes are connected than any RDoc can.

Still, use the examples to learn new things, not to cargo cult into your own project. Using code without understanding it is the fastest way to a poorly designed system.

In my example, maximum might not be the right thing to do in my project. I shouldn’t copy the line without learning more about it. Without understanding when it makes sense to use. But examples can teach you things you didn’t know before. And they’re a great way to decide what to learn about next.

Like any search, it’ll take some practice to get good results. But I’ve learned a lot from the code I’ve found, and I know you will too.

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.