Why Write System Design Docs

By Dave Allie
Published Jul 9, 20246 min read

What is a System Design doc

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.

Mode 1 Engineering vs Mode 2 Engineering

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.

Mode 1 Engineering - How less experienced engineers do it

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.
Mode 1 engineering - How engineers tend to build
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.
The local maxima of doing it by yourself
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.

Mode 2 Engineering - How the pros do it

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.
Hitting that global maximum
Taking the flowchart from Mode 1, and shifting left the documentation and review phases as far as possible gets us this:
Mode 2 engineering - How the pros do it
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.

Engineer growth and System Design docs

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!