If you can’t put it in words, you can’t put it in code
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:
- What you’re planning to do.
- Why you’re doing it.
- How you’re going to do it (including…
