Skip to contentComing soon: SprintProof for ChatGPT and Codex

Free template

Technical design doc and technical documentation template

Ten sections for deciding how a feature is built before it is built: the goals, the design, the data and API, the options you turned down, and what could go wrong. Each section says what to write and what reviewers ask.

Markdown pastes into Notion, Google Docs and Confluence. No sign-up.

In short

A technical design doc explains how a feature will be built before anyone writes code: the goals, the design, the data model, the API, the options you turned down, security and rollout. Reviewers check it before the build starts. This free template also covers technical documentation for after the software ships.

The template

Ten sections, each with what to write.

A design doc is read by the engineers who will build the feature, the ones who maintain what it touches, and security. Write each section for the reviewer who will ask “why not the simpler way?”.

technical-design-doc-template.md
blank, with guidance
  1. 01

    Context and goals

    Why this is being built and what the design has to achieve, in a page or less.

    • Which PRD or brief does this answer?
    • What must be true when it works?
    • What constraints apply: deadline, existing systems, team size?

    TipState goals a reviewer can check the design against, such as “works once and expires in 7 days”. “Be secure” cannot be checked.

  2. 02

    Non-goals

    What the design deliberately does not try to solve.

    • What would a reader assume this covers?
    • Which cases are left to a later design?
    • What does the design make harder on purpose?

    TipNon-goals stop the review from turning into a debate about everything nearby.

  3. 03

    Proposed design

    The approach, at a level where another engineer could build it, with the flow of the main case.

    • Which components are new or changed, and how do they talk to each other?
    • What happens step by step in the main flow?
    • Which existing system does it touch, and how?

    TipDescribe the riskiest flow in numbered steps. A diagram helps, but the steps are what get reviewed.

  4. 04

    Data model

    Tables, columns, indexes and constraints, and what is stored in what form.

    • Which columns, types and constraints are new?
    • Which queries need an index?
    • What is stored hashed, encrypted or not at all?

    TipWrite the queries the feature runs next to the indexes. An index without a query is a guess.

  5. 05

    API

    Endpoints or interfaces, who may call them, and the results and errors they return.

    • Method, path and purpose of each call
    • Who may call it, and what happens to others?
    • Which stable error codes can come back?

    TipList error codes now. Clients branch on them, and changing a code later breaks someone.

  6. 06

    Alternatives considered

    The other ways you could have done it, and why this one won.

    • What is the simplest option, and why is it not enough?
    • What did each option cost in effort, risk and later change?
    • Which option would you pick if a constraint changed?

    TipInclude the option a reviewer is most likely to suggest. It shows you looked, and saves the question.

  7. 07

    Security and privacy

    How the design can be abused, and what stops it. Includes personal data it stores or sends.

    • Who could misuse this, and how?
    • Which secrets, tokens or personal data are stored, and how?
    • Which limits and checks apply: rate limits, permissions, expiry?

    TipAnything that sends email to an address a user typed can be used for spam. Name the limit.

  8. 08

    Rollout and migration

    How the change reaches production safely, and how you undo it.

    • In which order do migration, API and interface ship?
    • Is there a flag, and who turns it on?
    • How do you roll back, and what happens to data written meanwhile?

    TipShip the additive migration first, alone. Then every later step can be rolled back without touching data.

  9. 09

    Observability

    How you will know it works in production, and how you will find out when it does not.

    • Which events and metrics are recorded?
    • Which failures raise an alert, and who gets it?
    • What would you look at first when support reports a problem?

    TipLog what you would need to answer a support ticket: who, which workspace, what happened. Leave out secrets.

  10. 10

    Open questions and reviewers

    What is not decided yet, who decides, and who has to approve the design.

    • Which decision belongs to another team?
    • Which answer would change the design or the estimate?
    • Who reviews, and what are they approving?

    TipName a reviewer for every area the design touches, such as security, billing or the team that owns sign-in.

Example

A design doc for team invitations, filled in.

The invitations feature as a design: the table, the token, the endpoints, the accept flow that touches sign-in and the one question that is still open.

team-invitations-design-doc.md
example, filled in
INV · DESIGN DOC · OWNER JONAS T. · IN REVIEWTeam invitations: technical design

1 · Context and goals

Workspace owners and admins need to bring colleagues in without asking us to add them by hand. They invite people by email, choose a role, see who has not accepted yet, and can resend or revoke. Invitees get a link that works for seven days and lands them in the right workspace.

  • An owner or admin can invite one or many people, and each gets a link that works once for 7 days.
  • Accepting from the link works signed out, signed in as the invitee and signed in as someone else.
  • Nobody can use the invitations to send spam from our domain.

2 · Non-goals

  • Domain auto-join: needs verified domains first
  • SSO and SCIM provisioning: comes with the SSO work in a later release
  • CSV import of invitees: pasting many addresses at once covers it for now

3 · Proposed design

Accepting an invite touches sign-in, so this flow is built and tried first.

  1. The admin submits addresses and a role. The API checks membership, role and the rate limit, then writes one invitation row per address and queues the emails in the same transaction.
  2. A worker sends the email. The link carries a random token. Only its hash is stored.
  3. The invitee opens the link. The accept page looks the token up by hash and shows one of four states: signed out, signed in as the invitee, signed in as someone else, expired or used.
  4. Signed out goes through sign-in and comes back to the same link. Signed in as someone else offers “switch account” and keeps the link alive.
  5. Accept marks the invitation accepted, adds the membership with the invited role and opens that workspace, all in one transaction.

4 · Data model: invitations

ColumnTypeNotes
iduuidPrimary key
workspace_iduuidReferences workspaces. Index with email
emailtextThe invited address, lower-cased
roletextOwner, admin or member, checked against the inviter’s role
token_hashbyteaSHA-256 of the token. Unique index. The token itself is never stored
invited_byuuidReferences users
expires_attimestamptzCreated at plus 7 days
accepted_attimestamptzNull until accepted. Set once
revoked_attimestamptzNull unless revoked

Indexes: unique on token_hash, and on workspace_id with email, for the pending list and the duplicate check.

5 · API

Method and pathWho may callResult and errors
POST /v1/workspace/invitationsOwner, adminCreates one or many. A repeat for the same pending email returns the existing one. 429 over the rate limit
GET /v1/workspace/invitationsOwner, adminPending invitations, paginated
POST /v1/workspace/invitations/{id}/revokeOwner, adminSets revoked_at. The token stops working at once
POST /v1/invitations/acceptSigned-in userBody holds the token. Errors: invite_expired, invite_used, invite_wrong_account

Every route checks workspace membership and role. Another workspace gets 404.

6 · Alternatives considered

OptionForAgainstDecision
Random token, hash storedSingle use and revoke are one column each. A leaked database does not leak working linksOne table lookup per acceptChosen
Self-contained signed tokenNo lookup to read the claimsSingle use and revoke still need a row, so the state is stored anywayRejected
Add the person directly, no linkNo accept stepThe invitee never agrees, and a typo adds a strangerRejected

7 · Security and privacy

  • Invites email an address a user typed, so they could send spam from our domain.Limit: 20 invites per admin per hour, per workspace, set in config. The 21st returns 429 with the time to retry. Every hit is logged.
  • Tokens are random, at least 128 bits, and compared in constant time.Only a hash is stored. The link works once, expires after 7 days and stops working on revoke.
  • Open: a forwarded link lets anyone who signs in accept, unless the token is bound to the invited email.

8 · Rollout and migration

  1. Ship the migration alone. It must run in under a second on a copy of production. The rollback script drops the table and touches nothing else.
  2. Ship the API and the email job behind a flag, team_invitations, off for everyone.
  3. Ship the modal, list and accept page. Try the accept flow in Gmail, Outlook and Apple Mail, then turn the flag on for our own workspace, then the design partners.

Rollback: turn the flag off. Pending invitations stay in the table and work again when it is back on.

9 · Observability

  • Logged: every rate-limit hit with workspace and admin ID; every accept error by code.
  • Counted: invitations created, accepted, expired and revoked.
  • Alert: more than 5% of invite emails failing in an hour, sent to the on-call channel.
  • Gap: bounces are not visible yet. See the open question on bounces.

10 · Open questions

  • What if the invited email already has an account?Jonas T. · Tue
  • What happens when an invite goes over the plan’s seat limit: block, warn or charge?Tom A. · Wed
  • Can anyone with the link join, or only the invited address?Jonas T. · Tue
  • How does the admin find out an invite bounced?Ken L. · Thu

10 · Reviewers

  • Product · Maria K.ApprovedScope matches the brief. Out-of-scope list looks right.
  • Tech lead · Jonas T.Pending
  • Design · Priya R.Changes requestedAccept page needs a “signed in as someone else” state.
  • Billing · Tom A.PendingSeat limit policy: block, warn or charge?

How to use it

How to fill it in, step by step.

Write the design doc before the code, then keep it short. Its job is to get the disagreements out while they are cheap.

  1. 01Start with goals and non-goals. Copy the done-when from the PRD and add the technical goals. Then list what the design will not solve.
  2. 02Describe the riskiest flow step by step. Pick the part the team knows least. Write it as numbered steps, and name every system it touches.
  3. 03Write down the data model and the API with the error codes. Add the indexes next to the queries that need them.
  4. 04Record the alternatives you rejected. Include the obvious ones. One line of reason each is enough.
  5. 05Walk through abuse and failure. What an attacker could do, what happens when the email bounces or the job fails, how you roll back. Add limits and logging where needed.
  6. 06List open questions and send for review. Give each question an owner and a date. Ask the owners of every touched system to review.

For users and operators

Technical documentation template: after it ships

In short: A technical documentation template is a reusable outline for documenting software after it is built. It covers what the system does, how to set it up and configure it, how to use it, the API, the architecture, troubleshooting, how to run it in production, and a changelog, so users and engineers can find answers.

A design doc comes before the build, for review. Technical documentation comes after it ships, for users and operators.

technical-documentation-template.md
11 sections
  1. 01Overview

    What it is, who it is for, and what it does not do.

  2. 02Getting started

    The shortest path from nothing to working, tested on a clean machine.

  3. 03Configuration

    Each setting: what it does, its default, allowed values and where it is set.

  4. 04Usage

    The main tasks, one heading each, written as steps.

  5. 05API reference

    One block per endpoint or function: who may call it, request, response and errors.

  6. 06Architecture

    A short picture of the parts and how data moves, with a link to the design doc.

  7. 07Security and permissions

    Who can do what, which personal data is kept and for how long, where secrets live.

  8. 08Troubleshooting

    Symptom, likely cause and what to do, one row each.

  9. 09Operations (runbook)

    Deploy, monitoring and alerts, on call, rollback and backups.

  10. 10Changelog

    Each version with its date, what changed and whether it breaks anything.

  11. 11Glossary and contacts

    The terms readers may not know, and who to ask.

Customise it: delete sections you don’t need, or write “none” so readers know it was considered.

Technical documentation vs technical design doc

When each is written, who reads it, who owns it and how long it lasts
When writtenAs the software ships, then kept up to dateBefore building, so reviewers can check the plan
AudienceUsers, developers and operatorsThe engineers who will build it, the ones who maintain what it touches, and security
OwnerThe team that owns the code, with one named owner per documentEngineering
LifespanAs long as the software runs, reviewed with every releaseUntil the design is approved and built, then kept as a record of why

Skip the blank page

Let SprintProof draft it with you.

Describe the feature and the planner asks the questions a reviewer would, then drafts the brief, done-when, not-now and parts with ranges. The check library adds the edge cases teams usually find mid-sprint.

Turn this into a reviewed plan

FAQ

Technical design doc and documentation questions

What is a technical design doc?
A technical design doc explains how a feature will be built before it is built. It covers the goals, the proposed design, the data model and API, the alternatives you rejected, security, rollout and open questions, so reviewers can find problems while changes are still cheap.
When do you need a design doc?
When the work touches a shared system such as sign-in or billing, adds a table, changes an API other code uses, or will take more than a week or two. A small, reversible change does not need one.
What is the difference between a PRD and a design doc?
The PRD says what to build and why, and product owns it. The design doc says how to build it, and engineering owns it. The design doc should answer the PRD’s requirements and open questions, and name the ones it cannot.
What is technical documentation?
Written material that explains how software works and how to use, set up, run and change it. It covers user guides, setup instructions, API references, architecture overviews, runbooks and changelogs.
What is the difference between technical documentation and a technical design doc?
A design doc is written before building, so reviewers can check the plan. Technical documentation is written as the software ships, and kept up to date so people can use and run it.
What should a technical documentation template include?
An overview, setup and configuration, usage, an API reference, an architecture overview, troubleshooting, operations or a runbook, a changelog, a glossary and an owner. Skip a section by writing “none” so readers know it was considered.

Turn this into a reviewed plan with SprintProof.

Describe the feature and SprintProof turns it into a plan: checked against a library of questions reviewers ask, estimated as a range with 50, 80 and 90% dates, and signed off before anyone starts.