Why Write System Design Docs
A system design document is a detailed overview of an engineering solution. It outlines the architecture and components
of the system, provides a high-level description of the design, and explains the rationale behind various design
decisions. It also serves as a communication tool among engineers, allowing everyone to understand the approach,
functionality, and thought process that led to the solution. Finally, it helps identify potential issues before
the implementation starts, saving time and resources.
Aditya Rohilla has great all-in-one
System Design Template, and while not all
sections are important for all projects, it’s a great template to get you thinking about your own system
design.
At Visibuild we write system design docs as part of our project work, and I’d encourage you to do the same.
Lots of engineers tend to build first and validate second. We come up with ideas in our heads, attempt to immediately
build them, and finally discover if it was the right approach at the end.
What great engineers do is invert that thinking. They validate ideas, gather feedback, and make adjustments before
writing a single line of code.
Writing a system design doc helps engineers to identify and resolve issues that would otherwise be found deep into
the implementation process. The identification and resolution typically happen when attempting to translate ideas out
of our brains and into written word (or code). So by forcing ourselves to articulate our ideas into a written plan, we
make them more concrete for ourselves and others, and catch these issues much earlier in the process.
Let’s call the natural (and often default) process “Mode 1 Engineering”. Engineers naturally gravitate towards
this mode. By emphasising the implementation, engineers acting in Mode 1 will find the shortest path there, often by
coming up with 1 or 2 ideas in their head and immediately implementing the best one.
Once the implementation is complete, the engineer will gather feedback to ensure what they’ve built will solve the
original problem and (optionally) retrospectively document the solution they came up with.
The issue with this approach is that it encourages engineers to approach a local maxima around their first thought. This
limits the overall outcome significantly. If issues arise during the implementation process that require significant or
structural changes, the sunk cost into the existing solution will discourage the engineer from doing complete rewrites
or rebuilds and instead draw them towards small modifications and improvements to allow the implemented functionality to
remain.
Also, when the reviewer’s first look at a solution is the completely implemented version, they’re much more likely to
accept the structural decisions made by the author, and only suggest minor changes or improvements.
Just like how we get better high-level fundamental approach feedback to visual designs when looking at fat marker
sketches, or greyscale mocks, we get much better approach feedback to system designs when we give the reviewer the whole
picture, prior to implementation. When reviewing fully implemented code or polished visual designs, the feedback will
often be minor nits and suggestions, not complete rethinks.
Typically in Mode 1 Engineering, known-unknowns
are discovered during the implementation phase, and unknown-unknowns
are discovered during the review phase. This is a very expensive way to discover issues, as it requires rework and
re-review to resolve them.
By contrast, what we’ll call “Mode 2 Engineering” takes a significantly different approach, inverting that process by
“shifting left” the documentation and review phases. By doing this, it allows them to get reviews on the approach and
feasibility from their team prior to implementing the solution. While the engineer may start at the same point in both
modes, Mode 2 Engineering allows them to iterate and learn as part of the ideation phase and reach the best possible
solution to the problem.
Taking the flowchart from Mode 1, and shifting left the documentation and review phases as far as possible gets us this:
What this looks like in practice is:
- In parallel, thinking of the solution while documenting your research, approach, and ideas into a system design doc
- Drilling into details which are important for the solution
- Gathering feedback and iterating on the approach before implementation
- Using your system design doc as a basis for your implementation tasks
While this process feels slow and uncomfortable for engineers who are extremely embedded in Mode 1 Engineering, once
adopted it results in better solutions and (surprisingly) faster delivery. Re-work and expensive review cycles
are completely eliminated by aligning everyone on the approach prior to implementation. Those pesky known-unknowns and
unknown-unknowns can be teased out long before implementation.
As engineers grow they become practised at being both the author and the reviewer for their own solutions and
pre-empting questions/suggestions which other reviewers may suggest. This brings them closer to the best solution before
they engage with additional feedback providers. This is a key part of engineer growth, and is a skill which takes a time
and effort to develop.
While it may seem like experts on solo journeys can just implement a solution without a document and get it right the
first time, they are still writing a (virtual) system design doc and reviewing it in their heads. Thinking through
designs from front to back, considering alternatives, and deeply understanding the existing state of the world. This is
what allows great engineers to think around corners, anticipate issues, and reach great solutions.
It’s a trap to attempt to emulate these solo-developers as it overemphasises the implementation phase, encouraging more
Mode 1 Engineering. Take a breath, a step back, and write a system design doc.
At Visibuild we’re working towards our product goals together, so collaboration is at the core of how we work. Getting
these thoughts out of heads and into writing is the most effective way we’ve found to get to the best answer together.
If you’d like to hear more about our product process, reach out!