Beeminder Forum

Documentation-Driven Development

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 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.

2 Likes

Agreed. Maybe a more general term for this idea is something like “specification-driven development”. Test-driven development and writing down types in a language with a static type system can both be seen as instances of this pattern (with the added advantage that they are machine-checkable!).

2 Likes

Welcome to 1984 @dreev :wink:

According to Donald Knuth,

literate programming provides higher-quality programs, since it forces programmers to explicitly state the thoughts behind the program, making poorly thought-out design decisions more obvious.

There is also Behaviour Driven Development which is like if literate programming and test driven development had a lovechild.

Notably, for Ruby:
https://rspec.info

And for Scala:
http://etorreborre.github.io/specs2/

The User Guide for the latter is, in fact, completely written as such a Spec and shows that you can easily write whole documents in there complete with a table of contents.

There is many more but these are the best ones I know of.

3 Likes

So perhaps the principle is:

Design your interface from the perspective of its consumer, then worry about implementation details.

I love that this insight spans multiple schools of thought.

2 Likes

I’m resurrecting this thread to bring up another fascinating thing I’m reading about: All powerpoint is strictly forbidden at Amazon. To have a meeting you have to write a 6-page paper and the meeting starts with everyone reading it in silence. https://slab.com/blog/jeff-bezos-writing-management-strategy . I kinda love it.

Also at Amazon: Employees pitching new products create fictional press releases. I love that too.

4 Likes