How to write a good design document

tl;dr

A design doc is a problem/solution/implementation (PSI) where we state the existing issue we are having today, the solution that we are proposing, and how we are going to implement it in our system.

---

The long version… 😅

As part of the SRE duties, we often find ourselves in the need to design a new system or a project. Explain why it’s needed, the alternative, and draft some high-level plans on how to implement it in our eco-system.

In this post, I’m going to share what in my opinion is a good design doc, the key elements of it, and how to present it to your peers and stakeholders.

In the basics, a design document is a very good tool to set a clear view of the direction we want to go, define our goals, set the work needed toward that, and kind of pitch sale our idea where we show some alternatives and a favorite approach.

Not all projects deserve a design doc, consider drafting a design document when your project is encapsulated in an epic task broken into a lot of sub-tasks – this would be a good indication.

So what does a good design doc looks like?

The basics

Give your document a title, continue with the author(s) name (more than one person can contribute), and the date when you started this design document (it can take a while to finish one), and the status of this document (draft / WIP / review / ready).

The problem(s)

What is the problem we want to solve and our current situation, don’t go in-depth, keep it high level and simple.

And I’m a bit cautious here on whether it’s a problem or problems (plural) as if we are talking about problems, they must share the same domain here.

So for example, we are having pipeline issues where messages are getting congested or lost in the way – we identified several causes for that as part of our investigation.

In this case, we can tackle problems in plural and state them in our design document, as later we are going to address how we plan to fix them.

Our problem statement sit at the top of the document as it’s our gate, the entry point to our document where we give the context and the high level overview.

The drive

In most cases when we reach a point that we need to re-design / construct a new solution in an existing system it came after an incident(s).

Giving examples of past incidents that would not have occurred if we have fixed those issues before is a good pitch tool, also goals to improve our system (saving cost, reducing latency) is another drive to our goal.

Get some nice charts and graphs and also supporting numbers – data-driven decision-making is the best approach here rather than guessing.

For some extra points – state non-goals that this process won’t cover and solve as long as they are correlated to this problem’s domain.

Progress and working agreements

Managers would love you more if you give them a nice timeline for your project with measurable milestones.

Your milestones for the project is also your success criteria where you commit to achieve certain improvement over the existing system or introduce new capabilities.

The solution

Nobody likes a person that always complains and doesn’t come up with a proper solution.
And so you guessed it right, after describing the problem and our drive to solve that problem we need to come up with a solution.

This is an area where a product manager (PM) can help you a lot to tell the story, define the roadmap, and set priorities – don’t underestimate the power of a PM – it’s a privilege to work with one.

Start with the big picture, give a high-level overview of what you’re going to fix or introduce, and then start to dive deeper into layer after layer.

Try to be as descriptive as possible, so that even if you are drop-dead (god forbid) tomorrow, someone will be able to take from where you left and continue your work, this becomes very crucial in our modern time where companies shift to remote distributed work.

When there are several paths to solve the issue, it would give extra credit to describe them and give your personal thoughts as the project leader on which path we should go with – explaining why that solution is better than the other.

It will show a lot of maturities doing so.

Implementation

The implementation is what we will later transfer into sub-tasks to our epic of this project,
there is no expectations to go deep into each step where it’s obvious and clear as our sub-tasks will have that extra explanation in any case.

Our tasks should include:

• Engineering work
• Communication
• Documentation
• Tests
• Alerts
• Production readiness

Before you start the actual work

Here is a fun fact, after I wrote that headline above, I just told myself – “Hey, the design doc is part of the actual work…”, so let’s give it a different headline “When your design doc is ready from your side”, sound better?

So… you wrote what is on your mind, you think it’s perfect – what next?

1. Try to get feedback from a few fellow engineers/managers
   1. Tech lead
   2. Someone outside your team with no relation to your project (you’re trying to see how clear is your idea and goals)

Socialize your document among your team members, and even schedule a tech review on that to gather feedback and ideas.

Once you feel confident with a solid solution, gather the stakeholders, and team leads that will have an impact by your project, set expectations, and a starting date so nobody will be surprised.

Communication is the key for a successful project.