Documentation-Driven Development

Tech
1

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.

2 Likes
2

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
3

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:

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
4

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
5

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.

5 Likes
6

@dreev or I guess more appropriately @bee and @adamwolf, I would like to point out

for behavior driven development in JavaScript. I don’t do JS myself so I have no experience with these but I do have an extensive background in BDD and from that perspective these seem worth a closer look. What are you using for testing currently?

2 Likes
7

I think that Documentation-Driven Development is useful for many reasons

  • writing documentation reminds you what is actually intended product, reminding to stop sidetracking, gold plating, excessive futureproofing and runaway refactoring or even rewrites of what works

  • writing documentations forces to think about architecture and design it at least a bit (see Donald Knuth quote)

  • writing documentation for features encourages to reduce number of features, options, poorly handled corner cases and other cruft, what is almost always beneficial

Though there are also big traps, documentation-driven may turn into hype-driven or scam-driven, like deliberately stupid architecture - because you really want to put “blockchain” or “machine learning” in your documentation.

Waves hand

And yes, my feedback may be useful but not as a representative sample of what general populations wants/needs/whatever.

3 Likes