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.

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.

This Rails blog post goes into full detail on the docrails project, but here’s the short and sweet version:

Never touch any source code in commits that get pushed to docrails. If you need to change code, make a pull request to the main Rails project. docrails is for changes to RDoc, guides, and README files.

docrails will occasionally be merged into rails, and vice versa. docrails has maintainers who ensure that no “poor” commits to docrails make it into the rails repo.

If you’re confident that your documentation fix is an improvement, just push to docrails!

If you want to expand (or just start) your “open-source portfolio,” docrails is a great place to begin.