Software Design Documentation Template in Markdown

November 11, 2026 · 13 min read

Software Design Document Template (With a Markdown Example)

A software design documentation template is a fixed outline for explaining how you'll build a system before anyone writes code. It covers context, goals and non-goals, the proposed design, alternatives, security, testing and rollout. Below you'll find a complete template in Markdown, what each section needs, and how to draw the architecture as Mermaid diagrams.

What Is a Software Design Document?

A software design document (often shortened to SDD or just "design doc") describes how a team plans to build something. The author writes it before implementation starts, and other engineers review it while changes are still cheap. It records the key decisions and, more importantly, the trade-offs behind them. Some teams call it a technical design doc, and a technical design documentation template follows the same outline as the one below.

Its readers are the reviewers who approve the approach, the engineers who build it, and whoever maintains the system a year later. That last reader matters most. When someone inherits a service, the first thing they look for is the doc that explains why it works the way it does. Docs written for the product's users are a separate job, covered by our product documentation template.

A requirements document says what to build and why the business needs it. A design doc says how you'll build it. If you want a formal reference, IEEE 1016 defines the content of a software design description. IEEE's site lists the 2009 edition as an inactive-reserved standard, so treat it as background reading rather than a rulebook.

When Should You Write a Software Design Document?

Write one when the solution isn't obvious or the decision is expensive to undo. Common triggers:

  • You're building a new service or replacing an old one.
  • The change crosses team boundaries, so other people depend on your API or data.
  • You're changing a data model, a storage engine or a public contract.
  • Two reasonable engineers would pick different approaches.

Skip it for small, reversible changes. Malte Ubl's write-up of design docs at Google puts it bluntly. If the doc only says how you'll implement something, with no trade-offs or alternatives, you'd have been better off writing the code. When the whole question is one decision, such as picking a queue, use a single architecture decision record instead of a full design doc.

The Software Design Documentation Template in Markdown

Copy this template into your repo as a .md file and replace everything in square brackets. The core sections follow the structure described in Google's design-doc practice. Testing, rollout, open questions and a decision log are added for the operational questions reviewers tend to raise.

# Design: [Feature or system name]

| Field | Value |
|---|---|
| Author | [name] |
| Reviewers | [names or team] |
| Status | Draft / In review / Approved / Superseded |
| Last updated | [YYYY-MM-DD] |
| Tracking issue | [link] |

## Context and scope
[What exists today, what is changing and why now. Link to the
requirements instead of copying them.]

## Goals
- [Measurable outcome the design must achieve]
- [Another outcome]

## Non-goals
- [Something a reader could expect that this design will not do]

## Assumptions and dependencies
- [Services, teams or decisions this design relies on]

## Proposed design

### Overview
[One paragraph a new teammate could read on its own.]

### Architecture
```mermaid
flowchart LR
    Caller[Caller] --> Service[Your service]
    Service --> Store[(Datastore)]
```

### Components
| Component | Responsibility | Owner |
|---|---|---|
| [name] | [what it does] | [team] |

### API
[Endpoints, events or signatures other teams will depend on.]

### Data model
[New tables, fields or indexes, and how existing data migrates.]

## Alternatives considered
| Option | Pros | Cons | Why not chosen |
|---|---|---|---|
| [option A] | | | |
| [option B] | | | |

## Security and privacy
[What data the system touches, who can access it, what could leak.]

## Observability
[Metrics, logs and alerts that prove it works in production.]

## Testing plan
- [ ] Unit tests for [area]
- [ ] Integration test against [dependency]
- [ ] Load test at [expected peak]

## Rollout and rollback
[Feature flag, migration order, rollout stages, and how to undo it.]

## Open questions
- [ ] [Question] (owner: [name])

## Decision log
| Date | Change | By |
|---|---|---|
| [YYYY-MM-DD] | First draft | [name] |

The metadata table at the top does a lot of quiet work. A reviewer can see at a glance whether the doc is a draft or approved, and the decision log shows how the design moved after review. Delete any section that genuinely doesn't apply, but write "None" under Non-goals and Open questions rather than removing them.

What Should a Software Design Document Include, Section by Section?

Each section answers one question a reviewer would otherwise ask in a meeting. Here's what belongs in each, with a vague line and a better one so you can see the difference.

Context and scope

State the facts a reader needs before the design makes sense: the current system, the problem and the boundary of this change. Keep it to a few paragraphs and link out for detail.

  • Vague: "Exports are slow and we need to improve them."
  • Better: "Finance pulls order data by hand from the admin panel each morning. This doc covers an automated nightly export, not the admin panel itself."

Goals and non-goals

Goals are outcomes you can check. Non-goals are things a reader might reasonably expect, which you've decided not to do. Google's guidance stresses that a non-goal isn't just a negated goal like "the system shouldn't crash".

  • Goal: "Every order from the previous 24 hours lands in one CSV before 06:00 UTC."
  • Non-goal: "Real-time sync to the finance system. A nightly file is enough for month-end close."

Proposed design

Start with an overview paragraph, then go deeper: an architecture diagram, the main components, the API surface and the data model. Show only the parts that affect the decision. Pasting a full schema or interface definition makes the doc long and quickly out of date.

Security, privacy and observability

These cross-cutting concerns are often short, but a missing one tends to stall review. Say which personal data the system reads, who gets access to the output, and which metric or alert tells you it's broken. A single line such as "The CSV holds customer emails, so the bucket allows access only for the finance role" answers most questions.

Testing, rollout and rollback

List the tests as a task list so you can tick them off in the pull request. For rollout, name the flag or migration order and the first group that gets the change. For rollback, write the actual steps, not "revert if needed". When the change ships, a release documentation template holds the full deployment checklist and rollback plan.

Open questions and the decision log

Open questions give reviewers somewhere to push back without blocking the doc. Give each one an owner. The decision log records what changed after review and why, which is the part future maintainers thank you for.

A filled-in example you can edit

Here's a cut-down version of the template filled in for a small feature. Edit it, and the preview renders the headings, the table and the task list. The Export DOCX button turns it into a Word file for reviewers who don't read Markdown.

Design: Order Export Service

Status: In review | Author: your name

Context

Finance needs a nightly CSV of all orders.

Goals

  • Export every order from the last 24 hours
  • Finish before 06:00 UTC

Non-goals

  • Real-time sync
  • Changing the orders schema

Proposed design

A scheduled worker reads the orders replica and writes the file to storage.

Alternatives considered

Option Cost Reversible
Nightly worker Low Yes
Change data capture High Partly

Open questions

  • Who owns the storage bucket?
103 words557 characters25 lines
Markdown

Adding Architecture Diagrams with Mermaid

A diagram written as Mermaid code lives in the same file as the text, so it changes in the same pull request and reviewers see the diff. GitHub renders Mermaid code blocks in Markdown files, issues, pull requests, discussions and wikis. The full syntax is in our guide to Mermaid diagrams in Markdown, so this section only shows how the diagrams fit a design doc.

Start with a system-context view: the new component and everything it talks to. For the order export example, the source looks like this:

```mermaid
flowchart LR
    Cron[Nightly scheduler] --> Worker[Export worker]
    Worker -->|read orders| Replica[(Orders read replica)]
    Worker -->|write CSV| Bucket[(File storage)]
    Worker -->|on failure| Alert[On-call alert]
    Finance[Finance team] -->|download| Bucket
```

It renders as a left-to-right flowchart. The two cylinders are data stores, and the labelled arrows show what flows between each pair:

When the order of calls matters, add a sequence diagram under the API or design overview:

```mermaid
sequenceDiagram
    participant S as Scheduler
    participant W as Export worker
    participant R as Read replica
    participant B as File storage
    S->>W: Start nightly export
    W->>R: Query orders from the last 24 hours
    R-->>W: Order rows
    W->>B: Upload the CSV file
    W-->>S: Report success or failure
```

That produces four lifelines with solid arrows for requests and dotted arrows for responses. If you'd rather build a diagram visually first, the Mermaid editor previews it live in your browser and exports PNG or SVG for slides. Teams that want a more formal set of views often borrow from the C4 model, which starts with the same system-context idea.

Alternatives Considered: Showing Why the Other Options Lost

This section shows you looked at other ways to solve the problem and explains why they lost. Google's guidance calls it one of the most important parts of the doc. A small comparison table keeps it scannable:

| Option | Cost | Complexity | Reversible | Verdict |
|---|---|---|---|---|
| Nightly batch worker | Low | Low | Yes | Chosen |
| Change data capture stream | High | High | Partly | Too heavy for one nightly file |
| Finance queries the replica directly | Low | Low | Yes | Exposes production data access |

That renders as a five-column table with one row per option. Follow it with two or three sentences on why the chosen option best fits the goals, and which non-goal made the heavier option unnecessary.

We prefer to draft this table before writing the proposed design, even though it sits after the design in the doc. If you write the design first, the alternatives tend to become straw men that justify a decision you've already made. Writing them first keeps the comparison honest.

How to Scale the Template for Small Features vs New Systems

Not every change needs every section. The Google article suggests a larger project's doc lands around 10 to 20 pages, while a "mini design doc" of 1 to 3 pages suits incremental work. Here's how we'd trim this software design documentation template:

ChangeSections to keepRough length
Bug fix or small refactorNone; explain it in the pull requestA paragraph
One-week featureContext, goals and non-goals, design overview, testing, rollout1 to 3 pages
New service or cross-team changeEvery section, including data model, alternatives and securityAround 10 to 20 pages
One hard-to-reverse choiceAn architecture decision record insteadOne page

The format has one real limitation. A Markdown file can't enforce review or sign-off, so the Status field only means something if your team's pull request process backs it up. Require approval from the named reviewers before merging, and update Status in the same commit.

Keeping the Design Doc in Your Repo and Exporting It for Reviewers

Store each doc next to the code it describes, for example docs/design/order-export.md, and open it as a pull request. Reviewers comment on specific lines, and the merged version becomes the approved design. Our guide to writing documentation in Markdown covers how to organise the wider docs folder.

When the design changes during implementation, update the doc and add a row to the decision log. A stale design doc is worse than none, because readers trust it.

Some stakeholders want a Word or PDF file instead of a link to a repo. Paste the Markdown into the Markdown to Word converter and export it as a .docx. Mermaid diagrams become PNG images in the Word file, so they look right but aren't editable there. Word and PDF exports run on our server and share a free pool of 3 a day, no account needed.

Starting from a blank page is the slow way. This software design documentation template gives you every section a reviewer looks for, with diagrams that live as code beside your text. Keep the doc short for small features, fill in every section for new systems, and log each change after review. Paste the template into the editor to fill it in with a live preview, then download the .md for your repo.