During the last weeks, I have been interviewing possible engineer candidates. One of my questions is about the knowledge of readme driven development. Interestingly, not one candidate had ever heard anything about readme driven development, but nearly 90% could precisely explain what test-driven development means. 

This small statistic surprised me and opened my eyes to the fact that our implementation of readme driven development at 6Wunderkinder must be something new in the IT industry. So I dedicate this (longer) blog post for a further insight into how readme driven development may be done under real-life conditions.

I read about readme driven development a while ago in a blog post by Github cofounder Tom Preston-Werner. I liked the approach, since it seemed the solution to many common issues during software development like documentation, collaboration, iteration, efficiency and the production of stable and readable code. And most importantly: a good feeling about adding a new brick to the house called software.

I introduced the idea of readme driven development to the team of engineers at 6Wunderkinder while we were brainstorming about the architecture of our next product called Wunderkit. The idea was well received and we agreed in unison to give it a try as long as it did not stand in the way of getting the work done.

We actually started doing readme driven development before we wrote any line of code for Wunderkit and so it is, until today, completely readme driven software. But how do we actually do this readme business?

I am a huge fan of object-orientation. Not just in the style of coding but in the way you encapsulate and duplicate solutions. The same goes for databases. That’s why we chose a document-oriented database for Wunderkit - it felt right and more natural to see data as an object and not as a bunch of joined rows.

And since our objects/classes are well encapsulated and own problem-solvers, we decided to do our readme driven development around this design principle. We agreed to follow this small, but very strict step-by-step set of rules when we design and code a new object (which is mostly a single class):

ITERATE IN YOUR HEAD, NOT IN YOUR CODE

• I do NOT code anything, yet!!
• I spend at least one day and one night to think about the object and the problem it solves
• I iterate the design of the object so long in my head until I think it is perfect and I am really proud of what I have done

THE README FILE

• I create a readme file and explain my object in very short words, using mostly examples to demonstrate the object’s interface and use markdown for formatting
• I arrange a meeting with my team-mates by e-mail (to avoid distracting their flow)

THE PRESENTATION

• I proudly present my readme file, containing my object, the solution and a possible magic algorithm, using a projector in a Mini-Me version of a Steve Jobs keynote
• My team-mates, who will later connect their objects to my object, will challenge my object’s interface and will make suggestions about making it better 
• My team-mates will challenge my overall object, my solution and my magic algorithm
• In 9 out of 10 cases, I will go back to the readme-creation phase and then present again the next day
• Don’t forget: until now I did not code one line!

DO IT, IMMEDIATELY, NOW

• When my team-mates finally love my “baby” I actually start coding, writing unit tests, etc. which will go extremely fast and will be very satisfying and efficient, since nearly no iteration and extra thinking is necessary anymore.

Normally, the readme driven development would end now. 

But we learned that a final revision is always good to do. So after I finished the coding of my object, I presented the code to my fellow team-mates (again with the help of the projector and the Steve Jobs kind of love for the software I produced) and ask them for their final iteration help. On the whole, everybody will be fine with what I coded because they already agreed on the design some days ago. Sometimes someone will provide an extra quirk to make some of my lines of code obsolete and we do a final polishing of my class during the code review presentation. And finally the object/class is ready!

Lessons Learned

After doing our implementation of readme driven development for several months, my team and I came to the conclusion that this way of developing software is the most efficient, most motivating and the fastest way to create beautiful and stable code. Of course, this may be just the case for our team where the individuals share a common sense of many things. 

I must admit, the first weeks of doing readme driven development can be a real pain. Especially when you have a great idea burning on your soul and you want to just hack it down. Immediately. At 3 am in the morning.

What we learned is that it’s actually a greater challenge and more fun to “code in your head” and iterate over and over again. When you finally present your “head-coded” solution to your fellow team-mates and receive their respect and applause you will understand about the value of the readme driven approach.