# How to write a technical design doc

> A technical design doc explains how you will build something and why. Learn the sections to include, how to compare options and how to get a useful review.

A technical design doc explains how something will be built and why this way. It is written so that other engineers can find the flaws while they are still cheap to fix.

Web page: https://kansohq.app/guides/how-to-write-a-technical-design-doc

Updated: 5 October 2026

## What a design doc is for

A design doc, sometimes called an RFC or a technical spec, is written before a significant piece of engineering. It does three jobs: it makes the author think the design through, it lets other people find problems early, and it leaves a record of why the system looks the way it does.

Write one when the work is hard to undo, touches several teams or parts of the system, or has more than one reasonable approach. For a small change, a few lines in the task are enough.

## The sections that matter

- **Context:** what exists today, and why it no longer fits. Link the product requirements.
- **Goals and non-goals:** what the design must achieve and what it deliberately does not.
- **Approach:** the design in a few sentences first, then the detail.
- **Data model and interfaces:** the shapes of the data and the contracts between parts.
- **Alternatives considered:** at least two, with the reason each was not chosen.
- **Trade-offs:** what you are accepting by choosing this design.
- **Rollout:** how it will ship, how it can be rolled back and how you will know it works.
- **Open questions:** what is still unknown and who will find out.

## Compare real alternatives

The strongest part of a design doc is the comparison. List the options, including the dull one that keeps things as they are, and say what each costs and what it buys. A design with no alternatives looks like a decision that was made before the doc was written.

| Option | What it buys | What it costs |
| --- | --- | --- |
| Keep the current queue | No migration | Retries still lose messages under load |
| Move to a managed queue | Retries and ordering built in | A new vendor and a migration |
| Write our own retry layer | Fits our data exactly | Months of work and a new thing to maintain |

## Plan the rollout

Say how the change will reach users: behind a flag, to a few customers first, or all at once. Say what you will watch, and the signal that means “roll back”. A design with no rollback plan is only half a design.

## Get a useful review

1. Send it to the people who will build it, the people who will run it and one person who has not been close to the problem.
2. Ask specific questions: “What breaks at ten times the load?” rather than “Any feedback?”.
3. Give it a deadline, and say who decides when opinions differ.
4. Write the decision and the reasons back into the doc. If it is important, record it as a [decision record](https://kansohq.app/guides/what-is-an-adr.md).

## What reviewers look for

- **A clear problem.** Do I understand what is wrong today, and why it matters?
- **Honest alternatives.** Were real options weighed, including doing nothing?
- **Failure modes.** What happens when a dependency is slow, down or wrong?
- **Scale.** What happens at ten times the load, or a hundred times the data?
- **Operations.** Who runs this, and how will they know it is healthy?
- **Reversibility.** If this is wrong, how hard is it to undo?

## How long should it be?

| Size of change | A good length |
| --- | --- |
| A change one person makes in a week | A few paragraphs in the task, or one page |
| A change one team makes in a month | Two to three pages |
| A change that touches several teams | Three to five pages, with a one-paragraph summary at the top |

Put the summary first. A reader who has to find the point on page four will stop reading on page two.

## After the review

When the review ends, change the status of the doc to approved, list the decisions that were made and link it from the tasks that implement it. Treat it as a living document while the work is in progress: if the design changes, update the doc, and note the date. When the work is done, mark it as implemented, so the next reader knows it describes what exists.

## A design doc in Kanso

Start from the [technical design template](https://kansohq.app/templates/technical-design.md), which has context, approach, data model, alternatives, trade-offs and rollout ready. Keep it in the same project as the product spec and the board, link the cards that implement it, and use code blocks for data shapes. See [Kanso Docs](https://kansohq.app/product/docs.md).

## Questions

### What is a technical design doc?

A technical design doc is a document written before significant engineering work that explains how something will be built, which alternatives were considered and what trade-offs were accepted.

### When should I write a design doc?

When the work is hard to undo, touches several teams or systems, or has more than one reasonable approach. For small changes, a short note in the task is enough.

### How long should a design doc be?

Long enough to let a reviewer find the problems, and no longer. Two to five pages is typical. Put the summary first so a reader can stop early.

### What is the difference between a design doc and a PRD?

A PRD says what to build and why. A design doc says how to build it. The PRD comes first, and the design doc is written against it.

## Keep reading

- [What is an architecture decision record (ADR)?](https://kansohq.app/guides/what-is-an-adr.md): An architecture decision record (ADR) is a short note on a decision, why it was made and what follows. Learn the format, when to write one and examples.
- [What is a PRD? How to write one, step by step](https://kansohq.app/guides/what-is-a-prd.md): A PRD is a product requirements document. Learn what goes in one, how long it should be, how to write it step by step and the mistakes to avoid.
- [How to plan a software release, step by step](https://kansohq.app/guides/how-to-plan-a-software-release.md): Plan a software release in seven steps: fix the date, freeze the scope, split the work by team, track blockers and decide go or no-go. With a checklist.
- [Technical design doc template for engineers | Kanso](https://kansohq.app/templates/technical-design.md): A technical design doc template with context, approach, data model, alternatives, trade-offs, rollout and open questions. Copy it, or start it in Kanso.
- [Decision record template (ADR) to copy | Kanso](https://kansohq.app/templates/decision-record.md): An architecture decision record (ADR) template with the decision, status, context, consequences and revisit condition. Copy it, or start it in Kanso.

## Parts of Kanso used

- [Kanso Docs](https://kansohq.app/product/docs.md): Pages with headings, to-dos, tables and code, kept inside the project they describe, next to its board and its release.
- [Kanso Boards](https://kansohq.app/product/boards.md): A board for each piece of work. Cards carry a priority, an owner, a due date and the criteria that say when they are done.

[Kanso home, with plans and prices](https://kansohq.app/index.md)