MARTYHAUGHT

A practice that I have my projects follow is a self-guided README file. The concept is simple. The README should guide you through everything you’d need to do to get this app up and running on your local environment. It seems like an obvious must have on projects yet I’ve encountered several that don’t do this.

As I value efficient use of time, I find having everything I need to get an app up and running in easy steps is huge. As a consultant I end up running easily a dozen apps each year. This README saves me time and makes sure I didn’t forget any important steps. There’s nothing as frustrating as doing the normal rails setup steps only to find an app failing due to some unusual dependency or missing data. Having the README avoids this issue. It’s especially helpful if I haven’t run an app in a long time and just want to make sure I don’t need to redo any of the steps.

The README is particularly useful for those new to the project. I find it valuable for both newer and experienced programmers. When your team has a culture of writing these READMEs you know when you come onboard a new project that it’ll be there for you to get you up and running as fast as possible.

Let’s explore what these READMEs should include. Before I get started, I delete all the boilerplate contents that the Rails generator puts in there.

Start off with the project’s name at top. Even though it’s implied by its placement at the root of your Rails app, I still like it there.

Next I like to put requirements for the app. Usually this is the version of Ruby, any required databases and other special services/libs that you may not have installed on your system. I don’t list gem dependencies in this area since Bundler handles that. I do assume that anyone installing the app has a Rails compatible environment.

The meat of the README will be the steps to get the app up and running. This includes steps like configuring your database.yml, copying and adjusting any special config, running bundle and any steps to seed or bootstrap your environment with necessary data. These are typically written out as shell commands so someone could copy and paste it into their prompt.

Next I like to include information on deploying the app along with basic data on where that is. This piece isn’t as necessary but we find it convenient. This is especially true when you have many different apps and some may be on Heroku while others are on other servers that may use Capistrano for deployment.

If there are common tasks that we do I like to call them out here. Perhaps you have some external service you infrequently pull down data from. Maybe you process csv files.

Finally, if there are any special notes or tips that I want the team to know about this app, they go at the end. If these notes are important to the setup process I’ll mention them above with a fuller explanation towards the bottom.

One key principle is I want these READMEs to be self-guided. I shouldn’t need to ask questions of the team as I follow the guide. Hopefully it’s fast with clear steps. If not, that’s a red flag that the README needs an update.

Speaking of that, the first task that a new person on the project (experience level doesn’t matter) has is to update the README as they setup their machine. If anything is stale or inaccurate, they update it. If something isn’t clear or they have questions on it, we look to see if something needs to be clarified or not. If there is room for improvement, they make it better as they go. This process also helps flush out any implicit steps that needs to be defined.

Though it takes some extra time for the README to be written and kept up to date, I truly believe it’s worth every minute spent on it. Even when I am solo on a side project I still do this. On several occasions I’ve been immensely thankful that I did.

One thought on the evolution of this idea is to do literate programming where the README not only provides the kind of human readable documentation mentioned above but is also executable commands. Even further is the notion of full machine setup automation or images, such as Boxen. Depending on your team that might be preferred. However, I’d start with getting your project READMEs into shape before going beyond.

blog comments powered by Disqus