How to write technical design docs

TLDR

Technical design documents (aka tech design docs or tech specs) are a great way of creating detailed game plans for features or solutions to technical problems without implementing any code. They can ultimately end up saving your team a lot of time.

Outline

• The importance of tech design docs
• When to create tech design docs
• Mage’s tech design doc template
• Purpose
• Background/Context
• Requirements
• Detailed design
• Implementation plan
• Tests
• Runbook

The importance of tech design docs

Tech design docs are the instructions for solving a technical problem or building out a feature. If you have one prepared, it can be handed off to another team member who may be less experienced or unfamiliar with the problem at hand, and they should still be able to solve the problem. Design docs can act as a form of documentation for other team members to refer to.

In addition, the process of creating a tech design doc forces you to think through the edge cases and various problems you may encounter, and come up with solutions to those problems. This process makes you code up solutions in your head, so when it comes time to actually write the code, the execution is much quicker because the mental heavy lifting has already been done.

Design docs should be done on a shared workspace (e.g. Google Docs or Notion) so that others can leave comments and provide feedback. As a result, design docs aren’t only great for delegating work and saving time, but also collaborating towards a technical solution.

When to create tech design docs

It’s generally a good idea to create a tech design doc anytime you’re trying to solve a technical problem that takes longer than a day to solve. Even if the solution only takes a few hours to implement, a design doc can still be useful.

However, the design doc for a large project versus a small feature will obviously vary quite a bit in length. A design doc for a small feature can essentially be pseudocode, which is fine if that achieves the purpose of the document. The main thing is that the design doc has a purpose, problem to solve, and a solution. There are common parts to a design doc that can be used as a template, which we’ll go into detail below, but not all of them have to be included in every single design doc.

Design docs usually aren’t needed for very small features or technical problems with very obvious solutions that require little time to implement. This is a bit subjective, but if a design doc won’t actually save you much time and the benefits of writing it aren’t clear, you probably don’t need to write one.

Mage’s tech design doc template

The sections below each pertain to a section of the design doc template that Mage team members start with when creating a new design doc.

At the top of the document, you should include the author’s name and the date the document was created or last modified. At Mage, a design doc is often written for one or multiple epics in Airtable, so including a link to the Airtable epic is helpful.

Purpose

The purpose describes what the service or feature does. Try to keep this to one sentence.

Background

Why do you need this feature? What problem are you trying to solve? What is the context for another team member reading this document?

Requirements

What are the outcomes this service or feature must exhibit? These could be metrics like response time or characteristics of a component built on the frontend (e.g. responsive to various mobile device sizes). You can include user stories here to describe requirements.

Detailed design

This is the longest part of the design doc and requires the most research, planning, and preparation. This is your engineering approach to solving the technical problem.

It can include pseudocode, database schemas, flow diagrams, wireframes, components, input validation, security considerations, API endpoints, sample API requests/responses, and countless other things.

You can also mention alternative approaches to solving the problem and the tradeoffs.

Implementation plan

There might be some overlap between the detailed design and the implementation plan, but this section includes the actionable items (i.e. epics and tasks) required to complete and ship the service/feature.

Tests

What tests will you write? How will you ensure this service/feature works? How will you know when this service/feature stops working?

Runbook

How do you launch this service/feature? How will you monitor it? How does someone else troubleshoot it?