How the best software engineers write technical designs (the blueprint for consistent results)

🎁 Tech design template to download for paid subscribers!

How do you consistently operate at your highest level as a software engineer?

We all have good and bad days, and it’s important to remember that there's more to life than work. Yet, as engineers, we strive to perform with the precision and consistency of professional athletes.

The key to achieving this?

Developing systems and processes that drive efficiency and excellence. At the core of these systems is one fundamental process: designing good software.

Why? Because every decision you make after a solid design will be more impactful than those made following a poor one.

In today’s article, we’ll break down the technical design process. By the end, you’ll not only understand the value of a robust software design but also have a downloadable template for your own designs.

“Winners and losers have the same goals. You do not rise to the level of your goals. You fall to the level of your systems - James Clear in Atomic Habits”

⭐ What you’ll learn in this post

1. Why and when to write a technical design

2. Sections to include in your design:

   

3. What to include in each section

❓ Why and when you should write a technical design

From a project perspective, writing a technical design is inefficient. You are dedicating a single person to the project – a bottleneck.

But it’s worth down the line.

It reduces ambiguity, aligns the team, and identifies workstreams to parallelize.

This process is not only valuable at the beginning of the project. Once completed, you’ll still find value in having documented your decisions.

Even for small functionalities, create a one-pager outlining the proposal and workstreams

⌨️ What are the sections to include

0. Document control

History of revisions, review panel for each revision, approvals from different interested parties.

Get the status of the document first thing.

1. Introduction

Here summarize the existing system. What it does, what needs covers.

Expose the problem driving this change and explain why it’s important and why now is the right moment to do it

2. Stakeholders

List teams interested in this project and why they care about it. include both clients and dependencies

Example:

• Infra Team: Will this design affect the main Ring AWS account?

• Foo Team: Foo will need to call Service in order to <>.

• Bar Team: Bar showed interested in <>, they want to consume the data in Service.

3. Requirements

• Functional requirements: What the system must do. Include here UI mocks if applicable

• Nonfunctional requirements: How the system must behave

Example:

1. The service must expose information about the state of <>, accessible by X ID.

2. Updates to <> must be visible within 10ms

4. Out of scope