This was originally a daily beemail last year.
It seems like every time I talk about principles of software engineering to you all I get jaw-droppingly insightful replies. No pressure. If you google “documentation driven development” it seems to be a lot of people saying that documentation is so important that you should write it first blah blah blah. But I think there’s a deeper insight here that I want to run by you:
Making design decisions – like deciding what to build – is really hard. (That’s not the deep part yet.) A trick that helps is to pretend the thing exists and fully write up how you’d describe it to the user. I’ve been surprised how much clarity I can end up with about the right thing to do by doing that.
I sometimes call it blog-post-driven development. Come to think of it, “beemail-driven development” would work too since I’ve used you all [originally meaning the daily subscribers but applies to forum participants as well!] as a sounding board for making product decisions aplenty.
There are downsides to this. Like how I floated the idea of requiring a credit card in order to create a goal and everyone freaked the frack out and we were too scared to do it for years and then finally we did and it was immediately obvious that it was way better and no one (well, maybe one person – you know who you are) minded a bit.
But you can always write the documentation or blog post and not actually publish it until the thing it describes exists. Which is the point: let the documentation guide what you build.
I feel like I need to say it another way to drive home the profundity of it. Maybe in another language? So far I’m making it sound too obvious. I think the key, and the part that you need to try for yourself, is to put yourself in the mindset of the thing already existing and then describe it. That forces a lot of design decisions that you’d otherwise weasel out of making by writing things like “and then we’d either do X or Y”. Not allowed! Commit to a decision and see where the document goes. You’ll often back yourself into a corner and have to backtrack. Which is wonderful, to be doing that before any code is written instead of after.
PS: See also our recent blog post on spec-writing.