Glad You're Ready. Let's Get Started!

Let us know how we can contact you.

Thank you!

We'll respond shortly.


NY Standup: Documentation interpolation and RVM, Brew and autolibs FTW

Interestings Grant Hutchins / David Lee

If you wrap the opening name of a Ruby heredoc in single quotes, its insides will act like a single-quoted string.

If you wrap the opening name in backticks, the heredoc will be immediately …

Read more

Read More

A Great Example of Vendor-Library Abstraction in ActiveSupport

Depending on what you're working on, you may have been bitten at least once by a heavy dependency on a third-party library.
This happens when you become very dependent on the API of someone else's library, and suddenly you can no longer use that library or its API.

When this is a possibility, the defensive approach to this problem is to write your own API to wrap that API, so that if you need to drop that vendor library, you only have to reimplement the way your wrapper works.

You might think that you only need to worry about this in large, complicated APIs, but it can be worthwhile to do even for a simple API.

ActiveSupport::JSON uses MultiJSON behind the scenes. Even though ActiveSupport::JSON has really only two publicly available "normal-use" methods (encode and decode which transform Ruby hashes back and forth with JSON objects), the Rails developers were wise enough to even wrap the specific error class that MultiJSON raises, as ActiveSupport::JSON.parse_error.

# File activesupport/lib/active_support/json/decoding.rb, line 50
def parse_error

This way, you can write something like

  obj = ActiveSupport::JSON.decode(some_string)
rescue ActiveSupport::JSON.parse_error
  Rails.logger.warn("Attempted to decode invalid JSON: #{some_string}")

And then if/when Rails switches from MultiJSON, you won't have to change anything in your code to deal with exception handling around JSON.

(PS. I wrote the documentation for that method recently, so that's why I had to link to the Edge Guides. If you haven't seen it, check out my article on how easy it is to contribute to the Rails documentation.)

Read More

Executable Documentation

I try to avoid writing static documentation. It gets old and out of date as soon as the next person comes along because it is logically far away from the code it describes, so event the best intended developers won't always be aware of the documentation dependencies. Since working at Pivotal I've enjoyed writing tests first with RSpec, which results in one form of executable documentation to describe behavior to other developers working in the code base. But what about when you need to express behavior to people outside of your code base? Maybe your stakeholders have a company requirement of documentation, maybe you're trying to entice third party developers to use your new HTTP API, or maybe you just want people to install your gem, what then? Your audience matters, and there's a variety of tools out there to use depending on your needs.

Read More


Good documentation goes a long way towards, not only helping others understand your code, but also simplifying re-use. Unfortunately, it seems that the moment documentation is written, it’s out-of-date from the code, especially if maintained separately in its own document.…

Read more

Read More

They practically couldn't make it easier to contribute to the Rails docs

If you ever spot room for improvement or an error in the Rails documentation -- and that includes the Rails Guides and the API docs -- they've made the process extremely easy. If you've been waiting for "the right moment" to start contributing to open-source software, this might be it.

Read More