Mark Needham

Thoughts on Software Development

Micro Services: Readme files

with one comment

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.

This document should stand on its own as a testament to your creativity and expressiveness. The Readme should be the single most important document in your codebase; writing it first is the proper thing to do.

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!

Be Sociable, Share!

Written by Mark Needham

February 25th, 2013 at 11:58 pm

Posted in Micro Services

Tagged with

  • Graham Lea

    The README might be a good idea while your projects are kicking off, but I think it’s just documentation which over time will develop all the problems of code documentation: requires updating, goes out of date, wastes time of readers and writers when it could be automated.

    I think a better approach is to maintain, for every project, a ‘runInDev’ script that, regardless of how the project runs, will start it up with the most sensible defaults for a development environment. This way, devs need zero knowledge of a project before they can get something up and running, which is ideal if the project is simply a dependency for something being tested and not something the developer actually wants to learn about.