I recently stumbled upon a very old (circa 2010) blog post by Tom Preston-Werner (the founder of GitHub) on “Readme Driven Development”.
This was not a concept I’d ever heard of before in my career, but the general idea is:
Do some planning about what you want to build upfront; first; before you write any code, tests, etc.
Write it down!
At the same time, don’t overdo it. Don’t over-plan.
If you try to make some very detailed / complicated specs, there’s no way it will end up being exactly correct once it meets reality.
As Mike Tyson once said, “Everyone has a plan until they get punched in the mouth”, and real life will punch your over-engineered, overly optimistic initial plans in the mouth.
Some benefits of this approach include:
Forces you to actually think through the project without the cost of actually having to code everything up first
It’s easier to write documentation upfront when you’re still excited about / motivated to do the project than at the end when you’re tired of it and just want to move on to the next thing
If you define the interface upfront in the README, others can start building things that rely on your software before it’s finished
Gives you clarity on what exactly you need to build
If you do this, you’ll always have at least some documentation
All that said, I’ll leave you with this quote:
“There must be some middle ground between reams of technical specifications and no specifications at all. And in fact there is. That middle ground is the humble Readme.”