By my latest count I have around 15 different micro services/applications checked out on my machine which comprise the system that I’m currently working on.

Most of these are Ruby related so it’s easy to figure out how to start up a local copy because it’s either bundle exec rails server if it’s a rails application or bundle exec backup if it’s a sinatra/rack application.

The clojure applications follow a similar convention and we use rake to run any offline tasks.

Despite these conventions there is still a reasonable amount of knowledge around how to actually get these applications to work that remains in people’s heads but doesn’t necessarily have to.

Although talking to each other is generally a good thing, an exercise that we tried at GDS was to try and document in the README file what someone new to an application would need to know to get it working.

They then tried to get it up and running while only referring to the instructions but noted down anything that didn’t make sense or any steps which seemed unnecessarily manual and could be automated.

This was almost certainly more frustrating than having someone show you what to do but it scales a bit better and reduces what I think isn’t a high value conversation.

I recently came across a blog post Tom Preston Werner wrote a couple of years ago titled 'Readme Driven Development' in which he goes further in suggesting that we drive out our applications from the README.

I don’t know if we need to go this far but as we more towards a future where we’ll be working with lots of different applications it would be nice not to have to remember everything about them in our head!