← journal

Readme Drive Development


A perfect implementation of the wrong specification is worthless. By the same principle a beautifully crafted library with no documentation is also damn near worthless.

Writing a Readme is absolutely essential to writing good software. Until you’ve written about your software, you have no idea what you’ll be coding.

distinguish Readme Driven Development from Documentation Driven Development. RDD could be considered a subset or limited version of DDD. By restricting your design documentation to a single file that is intended to be read as an introduction to your software, RDD keeps you safe from DDD-turned-waterfall syndrome by punishing you for lengthy or overprecise specification. At the same time, it rewards you for keeping libraries small and modularized.

Most importantly, you’re giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind

As a byproduct of writing a Readme in order to know what you need to implement, you’ll have a very nice piece of documentation sitting in front of you.

It’s a lot simpler to have a discussion based on something written down. It’s easy to talk endlessly and in circles about a problem if nothing is ever put to text.

Consider the process of writing the Readme for your project as the true act of creation. This is where all your brilliant ideas should be expressed.