Why you should write software design documents

scrollMany software engineers never write design documents. Design documentation takes time, and implementations often proceed so far without any documentation that if it happens, it’s an act of recording what has been done — a tedious task at the best times.

Many software engineers argue “the code exists, it’s running, it’s working, let’s move on and build the next thing.”


But this attitude means an engineer is not using one of the most effective techniques I know of to produce good designs. So before you start your next design, let me try to convince you that you should start with the design documents. Like unit testing, design documents take time but soon save time in a project’s life-cycle.

Design documentation is an integral part of the design process

It may seem that documentation is just about capturing decisions. It is that — but it can be so much more. You do not need to have an entire design in your head before creating documentation, because the act of writing down the design is a major part of the design process. It shows you where the holes are in your design. It forces you think at a much more comprehensive level about the system you are building than only designing-by-coding can.

Improve your Design by capturing Error cases and Failure scenarios

Writing documentation helps you think about the errors and failures at a system level. This is where so much of the power comes from writing down your design — it forces you to think about these failure cases, and then code for it. For example, say you’re writing code that sends e-mails. What should your system do if the e-mail service is down? Retry? At what interval? How will the Operations team be notified? How much does it matter?

What if you don’t know how a system should behave in an failure scenario? Write down a decision — some policy — and then review the decision with your team. Even if you know it’s probably not the right decision, by capturing that decision, it ensures it is discussed. But if you never write down anything related to handling failures,  a reasonable policy may never implemented in the system until it’s too late. The system may then behave unpredictably when the failure does occur, because the failure case was never considered.

Better Testing for Free

Without decent design documentation, it takes very experienced test engineers to create a good test plan. But good documentation can drive the test plan, and the test engineers will concentrate on testing all the failure scenarios you’ve outlined. They will do the hard work and they will thank you for it.

Helping New Hires

It always takes time for new engineering team members to get up to speed on a system and code base. Good design documentation is an enormous help. New hires will feel they have joined a professional team, a team that has thought deeply about what they are building.

Writing improves your thinking

The best way to improve your thinking is to write. It’s as simple as that. You may not fully understand what you need to build, or fully understand the technologies that you may need to use in the implementation, but writing about the design will help enormously. Writing clarifies and deepens understanding about the subject matter.

In my next blog post I’ll explain how to write design documents, and what they should contain.

One thought on “Why you should write software design documents”

Leave a Reply

Your email address will not be published. Required fields are marked *