Note: This post is from an old Pelican blog I used to have at simonh.me, which I found on a backup drive on 2025-01-07. It's probably of no use, but reposted for posterity!
Some years ago I read this: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html. It has been stuck in my mind ever since. Even though the author was addressing coders, I believe his advice can be applied much further. The entire article is worth reading (it's only a couple of screens full). He lists four reasons why RDD is worthwhile:
First:
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 about how something should be organized or what should be included in the Public API.
Second:
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. You'll also find that it's much easier to write this document at the beginning of the project when your excitement and motivation are at their highest.
Third:
If you're working with a team of developers you get even more mileage out of your Readme. If everyone else on the team has access to this information before you've completed the project, then they can confidently start work on other projects that will interface with your code.
Fourth:
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. The simple act of writing down a proposed solution means everyone has a concrete idea that can be argued about and iterated upon.
Can that same advice be applied to other areas of life, I wondered? I'm pretty sure it can. Here is my idea.
Let's say I want to learn Django, or French. Maybe, I want to build a shed. Any of these can be considered a project. Projects need to be managed in some way or other. Could a README be used to manage a project like that???
Title: Learning Flask Project
Date: 2016-01-03
Author: Simon Harrison
Version: 0.1
Purpose: To Learn the Flask Web Development Framework.
TODO:
* Find a book or tutorial to learn the framework.
* Write a 'hello world' app running on local server.
* Write and deploy an app to a remote server.
* Write and deploy an app that does something useful for me.
* Write an app that for someone else and host it on my servers.
CHANGES:
-
Version 0.2 of the README might look like this:
Title: Learning Flask Project
Date: 2016-01-05
Author: Simon Harrison
Version: 0.2
Purpose: To Learn the Flask Web Development Framework.
TODO:
* Write and deploy an app to a remote server.
* Write and deploy an app that does something useful for me.
* Write an app that for someone else and host it on my servers.
CHANGES:
* 2016-01-04: Found a good series of tutorials on Youtube. Working through them.
* 2016-01-04: Made a 'hello world' app. Really easy!
More to follow soon.
Thanks for reading.
