So, you’ve come up with a beautiful, elegant, solid software design. But to move forward you have to get it approved. And to get it approved, you have to communicate it to others. Because, unfortunately, having the idea in your mind is not enough to get it built as you envisioned it. Getting your design across effectively is not a simple task, and many software engineers are not skilled at it. But as most skills, your skill at writing design documents can be improved, I hope this post helps you on your way.

As we write a design document we should keep two main concerns in mind:

Purpose

In my opinion these are the three objectives of a good design document:

• Get buy-in for the high-level architecture from relevant stakeholders (engineering managers, technical leaders, engineers from other relevant groups).
• Provide a blueprint for implementation.
• Provide documentation (for historical reference, onboarding etc.)

But most importantly: A design document may include a summary of requirements, if appropriate – but it should not read as a wishlist. Someone reading a design document should get a clear idea of what you are planning to do.

Audience

Who will be reading the design document:

• People who need to approve/provide feedback on the design.
• People who need to do the work outlined in the document.
• The author (you’re not going to remember why you did any of this in a couple of months).

In addition to their role, readers may have varying context on the design:

• Internal readers who already know the background whose memory just needs to be refreshed.
• External readers or newcomers who have no or close to no context and need a high level overview of what this document will cover.

When we write a design doc we need to keep the purpose and the different audiences in mind so we can write the right thing in the right place at the right level of detail.

Now that we know why we’re writing a design document and for who, let’s get into what it should include:

Continue reading →