Readme Driven Development

Image for post
Image for post

RDD is quite a simple practice. Understandably the following “DD” would indicate some minute-to-learn-lifetime-to-master practice. However, fortunately not in this case.

Write your Readme first. That’s basically it. But why?

Whenever you start a software project, be it your own personal project or for a company you’re working for you should (wherever possible) strive to write code that is reusable, understandable and easily maintainable.

Everyone has a different perspective on which tools, practices and processes contribute towards better software. At the end of the day your software still has to work. This is easily forgotten when there is too much focus on getting it finished, or going all Beautiful Mind on the solution.

Working software is not just about the implementation (how it’s coded). Bug free software that nobody knows how to use is just as bad as software that cannot be used because it’s so full of bugs.

The Humble Readme

The Readme is the single most important file in your whole project. It should provide a quick overview of the objective of the project (its purpose, why it was created), installation instructions, known issues and just enough detail that someone that has never used your software before can get started quickly and easily.

Don’t get me wrong, your Readme is not all the documentation you will ever have/need. However, you might be surprised to know that a small Readme covers the vast majority of questions and cases for people seeking to use it.

If you write your Readme before you write any code you’ll get some awesome benefits:

  1. You will get a birds eye view about what you should, and how you can provide functionally through your public API. Making sweeping architectural changes are super easy at this point before any code has been written.
  2. Once you start coding you will have focus and clarity about what needs to be delivered and exactly how.
  3. It can also act as an indicator for yourself and others about how much progress is taking place while the project is being developed.
  4. If you’re working with other developers of teams mates you will have a close-to-perfect specification that other can start writing software against with less fear that specifications will change as the project progresses.
  5. Discussion is very important. It’s much easier to discuss something that’s written down. A Readme can be easily changed rather than endless discussion about how things should work when and if you get to them.
  6. Usually the most energised and exciting part of a project is at the beginning. This is the best time to write a small amount of documentation that will serve you and others throughout. Writing documentation afterwards is always a drag and I’d be very surprised if you remembered every implementation detail and known issue after it’s all said and done.
  7. Even the best thought out projects have changes, hopefully they are less due to misunderstanding and more due to providing more features but they are still enevitable and will most likely happen through development. Having a single document (hopefully in version control) acts as a perfect medium for communicating changes as they happen. It’s also worth noting that recording changes as you go is much easier than trying to remember them all afterwards, or working out the changes from the code.

Applying RDD to an existing project really requires its own article. For now, hopefully this has given you something to think about.

Originally published at on April 23, 2016.

Written by

I’m a data nerd and TDD enthusiast originally from Sydney. Currently working for Uber in New York. My thoughts here are my own. 🤓

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store