If you can’t put it in words, you can’t put it in code

Image for post
Image for post
@nickmorrison via unsplash

I often write design documents even if no one will read them.

There are a lot of resources out there on how to write good design documents. There are also many different ways to define what constitutes a design doc — what it includes, how long it is, how formal it is, etc.

For my purposes, a design doc is any document that you write before you begin the actual implementation. It can be long or short, formal or informal, etc. The point is it’s something you do independently of the implementation—and before.

Most of the known benefits of writing design docs center around organizational alignment. Design docs can help you plan, help you get input from others on your team or in your company, serve as a record for the future. At larger companies, they’re also a great educational channel. While experienced engineers debate pros/cons of different approaches, many other can watch from the stands.

I’m a big fan of design documents on large teams and at large companies, but I still find them tremendously valuable even if no one else reads them.

A good design doc includes, at some level of detail:

Being forced to write those things down (even if it’s in a few sentences or paragraphs plus a diagram or two) sets a minimum bar that can help solve a lot of software development problems.

It is, of course, entirely possible to sometimes begin with the implementation first, but in this case, you should treat the implementation as a discovery implementation or a prototype to collect some “on the ground details”. But once you have those details, then you write your design doc before beginning the real implementation.

Co-founder, Monarch Money. Ex-Quora, Google.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store