How to Write a Software Design Document (With an Annotated Example)

Not sure how to write a software design document? Follow 6 simple steps, see a full annotated example, and copy a template for your next review.

TL;DR

  • A software design document explains how you plan to build something before you build it. It covers the design, the options you dropped, and the risks.
  • Not sure how much to write? If there's a lot of work or the best approach isn't clear, write a full document. For small changes, one to three pages is enough.
  • Every document needs the same core: context, goals and non-goals, the design, alternatives considered, and a plan to test and release it.
  • The example below is a complete document for a small system, with a note on every section. There's also a template you can copy.
  • Ask reviewers to comment on the page itself, and use page history to see what changed after review.

Many software design documents don't work well due to one of two reasons. Either nobody has the time to write one, so the design lives in a chat thread until the person who remembers it leaves. Or someone puts real effort into a forty-page template, and nobody gets past the contents list.

You can aim for the middle. A good document is short enough to read in one go, and clear enough that a reviewer can disagree with it. It also records why you picked this design over the others, and that's the part of the document you'll be glad to have in a year.

Below, we'll write one together from scratch for a small system: expiring share links for an invoicing app. Every section of the finished document comes with a note on why it's there and what reviewers usually question, so you know what to expect. You also get a template to copy, a simple way to decide between a full document and a short version, and a walkthrough of how a review works in comments and page history.

What Is a Software Design Document (SDD) in Software Engineering?

A software design document (SDD) describes how a system or feature will be built. You usually write it before the code so your team can review the approach. This is because changing a design at this stage costs just an edit, but changing it after the code is written costs a lot more.

It comes between two other pieces of work. The product requirements document (PRD) says what you're building and why, and the design document says how. The building starts after that. If you haven't written the PRD yet, our guide on how to write a product requirements document covers that first step.

Now, you'll hear phrases like "design doc," "technical design document," and "tech spec" for the same kind of document. Teams don't usually agree on where one ends and the next begins. So, in this post, "software design document" means the short, practical version engineers write for each big piece of work.

There's a formal standard behind the idea too. IEEE 1016 describes what a software design description should contain. IEEE lists the 2009 edition as "Inactive-Reserved," so it's no longer an active standard. Most teams today use a lighter format with the same core sections, and that's the format in this post.

Software Design Document vs PRD, Tech Spec, ADR, and RFC

These documents overlap, and the quickest way to tell them apart is the question each one answers.

Document

Question it answers

Usually written by

How long it stays useful

PRD (product requirements document)

What are we building, and why?

Product manager or product owner

While the product is being built, and it should be updated when requirements change

Software design document

How will we build it?

The engineer or tech lead doing the work

Until the design is built, then it stays as a record

Tech spec

How will we build, test, and release it?

The engineer or tech lead who owns delivery

While the system is being built and maintained

ADR (architecture decision record)

Why did we pick this one option?

Whoever made the decision

It stays as a record, and if the decision changes, a newer ADR replaces it

RFC (request for comments)

Should the team agree to this proposal?

Whoever is proposing the change

Until the team decides. The result can be an ADR

Some teams treat a design document and a tech spec as the same thing. So, use the table as a starting point, and expect your own team to draw the lines a little differently.

When Do You Need a Software Design Document?

If the best approach isn't obvious, or the work touches several parts of a system, a design document will be needed. But if the answer is already clear, you can skip it, because a document that only repeats what the code says would take effort without helping anyone.

Size matters too, and it's fine to keep things small. A short version of one to three pages works well for small changes, and larger projects can take more pages. It's hard to say exactly what counts as big, and there's no official cutoff, so to keep things simple, this post uses two weeks of work as the line.

Situation

What to write

Bug fix or small change with an obvious solution

Nothing. Describe it in the pull request

Up to two weeks of work, one component

A short version (one to three pages): context, design, alternatives, test plan

More than two weeks, or several components

The full document in this post

Treat these as rules of thumb, not strict rules. You know your team best, so trust your own judgment where it differs.

How to Write a Software Design Document in 6 Steps

  1. Collect the requirements and limits: Gather what you need from the PRD, then talk to the people who own the systems this work will affect. Write down any hard limits, such as a database you can't change or a team that has to approve the design. Knowing these early saves you from surprises later.
  2. Write the context, goals, and non-goals first: Do this before any design. You and your reviewers should agree on the problem before you argue about the answer. Non-goals are things that could reasonably be goals, but that you've chosen to leave out.
  3. Sketch the design, then write it up: Draw the main flow before you write about it. If you can't draw it, you're not ready to write it.
  4. Write the alternatives as you go: Write down each option you consider and the reason you decided against it, while the reasons are still fresh in your mind.
  5. Ask one person to read it first: Pick someone who will be honest about what's confusing, and don't worry if they find a lot of confusing spots. It's easier to fix those spots now than in front of the whole group.
  6. Open it for review and set the status: Put the status at the top so nobody has to guess whether the page is a draft or a decision, and name your reviewers so they know it's their turn to read.

The example and the template below put each of these steps to work.

What Goes in Each Section of a Software Design Document

This post uses ten sections. Each one answers a question a reviewer would otherwise ask you in a meeting.

Section

Question it answers

Typical length

1. Header and status

Who owns this, who reviews it, and what state is it in?

5 lines

2. Context

Why are we building this, and what exists today?

1 to 3 paragraphs

3. Goals and non-goals

What counts as done, and what are we leaving out on purpose?

3 to 6 bullets each

4. Proposed design

What are we building, concretely?

The longest section

5. Alternatives considered

What else could we have done, and why not?

A table plus 2 sentences

6. Security and failure handling

What happens when it's attacked or breaks?

A short list

7. Testing

How will we know it works?

A short list

8. Release, monitoring, and undo plan

How does it ship, and how do we undo it?

A short list

9. Open questions

What don't we know yet?

A short list with owners

10. Decision log

What changed during review, and why?

Added as review goes on

The lengths are only rough guides, so don't worry if your sections come out a little shorter or longer. Next, you'll see every section filled in.

The example below is for a small invoicing app called Ledgerline. The company, the people, and the requirements are all made up so you can focus on the document. The feature lets a user send a client a link to an invoice PDF. The link works without logging in and stops working after a set time.

It's small enough to read in one go, and big enough to need a design. It touches the API, the database, and file storage, and there's a security question in the middle. We'll say it's about three weeks of work for two engineers. That's over the two-week line from earlier, so a full document makes sense.

Each section shows the text as it would appear in the document, in a quote block. Under it you'll find why it's written that way and, for most sections, what reviewers usually question.

1. Header and Status

  • Title: Expiring Share Links for Invoices
  • Author: Dana Okafor
  • Reviewers: Marcus Lee (backend), Sofia Reyes (security)
  • Status: In Review
  • Last updated: [date of last edit]
  • Related: PRD, Share Links for Invoices

Why it's written this way: The status line tells a reader whether they're looking at a draft or a decision, so it goes first. Naming what each reviewer is covering keeps feedback from landing on the wrong person.

What reviewers usually question: A missing owner or missing reviewers, because if nobody is named, nobody is responsible for the document.

2. Context

Today, a client has to create a Ledgerline account before they can view an invoice, which is an extra step for someone who just wants to see it. Users have asked to email an invoice and let the client open it with one click.

Why it's written this way: Context is what a new teammate reads a year from now. Write it for someone who wasn't in the room, and stick to facts. Also, requirements belong in the PRD, not here.

What reviewers usually question: Context that slides into requirements, or that assumes the reader already knows the product.

3. Goals and Non-Goals

Goals

  • A client opens an invoice from an emailed link without creating an account.
  • Links expire.
  • The sender can turn a link off (revoke it).

Non-goals

  • Password-protected links.
  • Per-view analytics.
  • File types other than PDF.

Why it's written this way: A non-goal isn't the opposite of a goal. "The system shouldn't crash" is not a non-goal. A real non-goal is something a reasonable person might expect that you're leaving out on purpose. Listing them keeps review from turning into a debate about scope.

What reviewers usually question: "Can we also add password protection?" The non-goal is your answer, so you can point to it instead of arguing.

4. Proposed Design

When a user shares an invoice, the API creates a share link. The link carries a random 32-byte token, written in a form that's safe to use in a web address. The token is tied to one invoice and an expiry time. We store only a hash of the token, never the token itself. A hash is a scrambled version of a value that can't be turned back into the original.

When a client opens the link, the API hashes the token from the address, looks up the matching row, and checks that the link hasn't expired or been revoked. If it's fine, the API sends back the invoice PDF from file storage. Expired, revoked, and unknown links all get the same response, so a visitor can't tell which one they hit.

sequenceDiagram
    participant Sender
    participant API
    participant DB as Database
    participant Files as File Storage
    participant Client

    Sender->>API: Create share link for an invoice
    API->>API: Generate 32-byte token and hash it
    API->>DB: Insert row with token_hash and expires_at
    API-->>Sender: Return the link (shown once)
    Client->>API: Open the link with the token
    API->>DB: Look up the row by token hash
    DB-->>API: Row with expires_at and revoked_at
    API->>Files: Fetch the invoice PDF
    Files-->>API: PDF
    API-->>Client: Send the PDF

Data model, the share_links table:

Column

Type

Notes

id

uuid

Primary key

invoice_id

huuid

The invoice being shared

token_hash

text

Hash of the token, unique

expires_at

timestamp

Set when the link is created

revoked_at

timestamp

Empty until the link is revoked

created_by

uuid

The user who created the link

created_at

timestamp

When the row was created

Endpoints:

Method and path

What it does

Who can call it

POST /api/invoices/{id}/share-links

Creates a link and returns it once

The invoice's owner

DELETE /api/share-links/{id}

Revokes a link

The user who created it

GET /s/{token}

Returns the invoice PDF

Anyone with the link

Key decisions:

  • The token is 32 random bytes, made with a secure random generator.
  • We store only the hash of the token. The sender sees the link once, when it's created.
  • Links expire 14 days after creation by default. A sender can choose a longer expiry, up to 30 days.
  • A link stops working at expires_at, not after it.
  • Expired, revoked, and unknown links all return the same response.

Why it's written this way: Start with a short overview, so a reviewer who stops after one paragraph still knows the design. The data model and endpoints are tables because reviewers check them line by line. Storing only the hash means that if the database leaks, the leaked values can't be pasted into a web address to open an invoice.

What reviewers usually question: What happens right at the expiry time, which the fourth decision answers. And why you store a hash instead of the token, which the second one answers.

5. Alternatives Considered

Option

How revocation works

What it stores

Verdict

Random token with a database lookup

Set revoked_at on the row. It takes effect right away

One row per link

Chosen

Signed token with the expiry inside it

A signed token stays valid until it expires, so you'd need a list of revoked tokens, which brings the database back

Nothing per link, until you add that list

Rejected, because revoking is a goal

Presigned storage URL (for example, from Amazon S3)

The URL can't be revoked one at a time. You'd have to remove the permissions of whoever signed it, which also breaks other links they signed

Nothing per link

Rejected, because we'd lose control of revoking a single link

We chose the first option because revoking a link is a goal. The cost is one extra table to look after, and one database lookup every time someone opens a link.

Why it's written this way: Reviewers often read this section first, so give every rejected option its real reason for losing. Don't write a weak option just to make the winner look good.

What reviewers usually question: "Why not signed tokens? It's simpler." If the table already answers it, you save a round of comments.

6. Security and Failure Handling

  • Rate limiting: The open-link endpoint is rate limited per IP address, which means each address can only make so many requests in a set time. This slows down anyone who tries one link after another until one works.
  • Comparing secrets: Anywhere the code compares a token or a hash, it uses a comparison function that takes the same amount of time whether the values match or not. This matters because a slightly faster or slower reply could otherwise give an attacker a small clue about how close their attempt was.
  • Same response: Expired, revoked, and unknown links return the same "link not available" page with the same status code.
  • Logs and referrers: The token is part of the web address, so request logs hide it. The response also sends the header Referrer-Policy: no-referrer, so the browser doesn't pass the link's address on to other sites.
  • Database down: If the database can't be reached, the endpoint returns a 503 Service Unavailable error, not a "not found" page. A 503 means a temporary problem, so a client won't assume a valid link has expired.

Why it's written this way: Give each concern one short item. If a risk matters, say what happens when it happens. Security and similar concerns that cut across the whole design deserve their own section so they don't get lost.

What reviewers usually question: Tokens leaking through logs and referrers, and what the client sees when the database is down.

7. Testing

  • Unit tests for the expiry boundary, including a link opened at exactly expires_at.
  • An integration test that revoking a link takes effect right away.
  • A test that expired and revoked links return identical responses.
  • A test that repeated requests from one IP address get rate limited.
  • A test that the endpoint returns a 503 when the database is down.
  • A manual check of the link in a real email app.

Why it's written this way: A test plan is the risks above turned into checks. Each test should map back to something in the design.

What reviewers usually question: Failure paths with no test.

8. Release, Monitoring, and Undo Plan

  • The feature is released behind a flag, which is an on/off switch. We can turn it on for one workspace at a time, so any problem only affects a small group first.
  • We'll keep an eye on two numbers: how many links are created each day, and how often the open-link endpoint returns "link not available." A jump in the second number would tell us something is wrong.
  • Undo plan: turn the flag off. The database change only adds a new table, so nothing else needs to be reversed.

Why it's written this way: Say how you'll know something is wrong and how you'll undo it. Adding a brand-new table is easy to undo, because it doesn't change anything that already exists. If something goes wrong, you turn the feature off, and the rest of the app keeps working exactly as before.

What reviewers usually question: No way to spot a bad release.

9. Open Questions

  • Should a sender be able to extend a link's expiry? Owner: Dana. Decide before approval.
  • Should a sender be able to see a link again after creating it? Today they can't, because we store only the hash. Owner: Marcus. Decide before approval.
  • Which hash function do we use for token_hash? Owner: Sofia. Decide before approval.

Why it's written this way: Open questions show what the design hasn't settled yet. And without an owner and a deadline, they stay open forever.

What reviewers usually question: Questions with no owner.

10. Decision Log

Empty until review starts. Entries are added as the design changes.

Why it's written this way: The log records what changed during review and why, so a reader a year later doesn't have to reread the comment threads. The review section below shows an entry being added.

Software Design Document Template (Copy and Paste)

This is the same ten sections, empty, with a prompt under each heading.

FEATURE OR SYSTEM NAME

Author: [Name]

Reviewers: [Names and what each person reviews]

Status: Draft | In Review | Approved | Implemented | Superseded

Last Updated: [Date of last edit]

Related: [Link to the PRD]

1. CONTEXT

Describe what exists today, why it needs to change, and the problem this proposal aims to solve. Include enough background for someone unfamiliar with the project to understand.

2. GOALS

1. What should this proposal achieve?
2. What does success look like?
3. What criteria must be met for the work to be considered complete?

3. NON-GOALS

1. What is intentionally excluded from this proposal?
2. What might people expect to be included but is outside the scope?

4. PROPOSED DESIGN

Start with a short summary of the proposed solution that reviewers can understand on its own.

Include:

1. A diagram showing the main flow.
2. The data model.
3. Any API or interface changes.
4. Key design decisions and a brief reason for each.

5. ALTERNATIVES CONSIDERED

| Option | What It Costs | Why It Was Chosen or Rejected |
|---|---|---|
| [Option] | [Trade-offs or costs] | [Reason] |

6. SECURITY AND FAILURE HANDLING

Explain how the system handles potential attacks, security risks, and dependency failures.

1. What happens if a dependency becomes unavailable?
2. How does the system respond to security threats?
3. What happens when something fails?

7. TESTING

List the risks identified above and describe how each one will be tested.

8. RELEASE, MONITORING, AND ROLLBACK PLAN

1. How will the feature be released?
2. What will you monitor after launch?
3. How will you identify problems?
4. How can you roll back the changes if needed?

9. OPEN QUESTIONS

1. [Question] | Owner: [Name] | Decision Deadline: [Milestone]

10. DECISION LOG

1. [Change made during review] | Reason: [Why the change was made]

Paste it into a page in your wiki, a Markdown file in your repo, or a word processor. If a section doesn't apply, delete it and leave a one-line reason so reviewers don't wonder whether you forgot it.

Where Should You Keep the Design Document?

There are two good options:

  • A Markdown file in your repo: It keeps the document next to the code. This suits a small team where everyone who reviews it already works in the repo.
  • A shared wiki page: This suits a team where some reviewers don't work in the repo, and where you want comments and page history in one place.

The deciding question is who needs to review it.

If you're still deciding where to keep all of this documentation, see our guide to the best documentation tools for engineering teams.

How to Get a Software Design Document Reviewed in Docmost

Review works best as a conversation on the page itself. In Docmost, a reviewer selects the text they want to discuss, clicks the comment icon in the floating toolbar, and types a comment. Comments show up in a comments panel on the right side of the page, with an Open tab and a Resolved tab. Resolving comments is a paid-edition feature.

Page history helps too. Docmost saves it automatically as people edit. A reviewer can open the page menu, click Page history, and pick a version to see a highlighted difference against the current page. They can also compare two versions with each other.

Here's how a review discussion on the alternatives table could look. The names and comments are made up, like the rest of the example.

Marcus Lee, commenting on the Alternatives Considered table: Why not signed tokens? Fewer moving parts.

Dana Okafor, commenting: Revoking a link is a goal. A signed token stays valid until it expires, so we'd need a list of revoked tokens, which brings the database back. I've added that to the "How revocation works" column.

Marcus Lee: That works for me.

A reviewer's comment can also change the design. Sofia asks for a shorter default expiry, and Dana edits one line:

Before: Links expire 30 days after creation.

After: Links expire 14 days after creation by default. A sender can choose a longer expiry, up to 30 days.

Sofia can then open Page history, pick the version from before the edit, and see the change highlighted. She doesn't need to reread the whole page. Dana then adds an entry to the decision log:

Decision log: Default expiry changed from 30 days to 14 after security review. Senders can still choose a longer expiry, up to 30 days.

The Proposed Design section in the example above already shows the version after this change.

Reviewers can also ask the same questions of every document:

  • Is the problem clear?
  • Are the non-goals real?
  • Is each alternative treated fairly?
  • What happens when each part fails?
  • How will we know it's wrong after release?
  • How do we undo it?
  • Does every open question have an owner?

A wiki page doesn't update itself, so it's important to put an owner on the page. See how to assign page owners and review dates in a wiki. Docmost's page verification workflow, which handles review requests and approvals, is part of the Enterprise edition.

If your team uses an AI assistant, the Business and Enterprise editions of Docmost can connect it through MCP (Model Context Protocol). The assistant can then search, read, create, and update pages, including a page like your design document. See how to connect your wiki to Claude, ChatGPT, or Cursor with MCP.

How to Keep a Software Design Document Useful After Release

Give the document a status that moves as the work does:

  • Draft: You're still writing it, and nobody needs to review it yet.
  • In Review: Reviewers are commenting, and the design can still change.
  • Approved: The team has agreed, and the build can start.
  • Implemented: The design is built, and the document now serves as the record.
  • Superseded: A newer document replaced it, and the page links to that one.

Fix small errors in place. If the design changes in a big way, write a new document and link the two. That way the original still explains why you made the first choice.

Common Software Design Document Mistakes That Make Reviewers Stop Reading

  • Writing it after the code: Catching design problems early is the whole point, because changes are cheap at that stage. Once the code exists, reviewers can't change much. If it's already written, write a short record of the decisions and label it as a record.
  • Listing goals with no non-goals: Every reviewer then adds their own goal. Name what you're leaving out and why, so the reasoning is clear.
  • Hiding the design in an image: A screenshot of a diagram can't be edited by your team. But a Mermaid diagram is written as plain text, so your team can edit it, and Docmost draws it right on the page. To add one, type / in the editor and pick Mermaid diagram.
  • Skipping the alternatives: The alternatives section forces you to think about what else would have worked. Without it, reviewers make up their own options, and you argue about choices you never wrote down.
  • Writing an implementation manual: A design document should rarely contain code. If yours reads like instructions for typing the code, you may not need the document at all.
  • Leaving no owner after approval: A page only gets updated when someone knows it's theirs to look after. Put a name on it.

Do You Still Need a Software Design Document If You Work in Sprints?

Yes, for work that's unclear or costly to change. For the rest, a short one is enough, or nothing if the answer is obvious. A one-to-three-page version is well suited to small improvements and subtasks inside a sprint.

The usual objection is that design documents slow a team down. Writing one is extra work, and it's only worth it when it saves you from a bad design. That's why the question to ask is whether the document will change a decision, not whether your team uses sprints.

Frequently Asked Questions

  1. What Is a Software Design Document in Software Engineering?

A software design document describes how a system or feature will be built. It's written before the code so the team can review the approach. It comes after the product requirements, which say what and why, and before the build.

  1. How Long Should a Software Design Document Be?

Small changes need one to three pages. Larger projects can run longer. If a document grows far past what a reviewer can read in one go, split the problem into smaller parts and give each its own document.

  1. Who Writes and Approves a Software Design Document?

The engineer or tech lead doing the work usually writes it. Reviewers are the people who own the systems it touches. Who gives final approval depends on your team. Some teams let the author decide after hearing feedback. Others name a person or group to decide. Whichever you pick, write it on the page so nobody has to guess.

  1. Is There a Standard Format for a Software Design Document, Like IEEE 1016?

IEEE 1016 is a formal standard for software design descriptions. IEEE lists its 2009 edition as Inactive-Reserved. Most teams use a lighter format with the same core sections: context, goals and non-goals, the design, alternatives considered, and a plan to test and release it.

  1. What Should You Do When Reviewers Disagree About the Design?

Keep the discussion in the comments on the page and give the reason for your choice. If it changes the design, update the page and add a line to the decision log. Decide who makes the final call before review starts, and name that person on the page.

  1. Should a Software Design Document Include Code?

Rarely. Keep the design document about the decisions and what each one costs. A short snippet is fine when it makes something clearer, such as the shape of an API request. Leave the full implementation in the repo.

  1. What's the Difference Between a Software Design Document and a PRD?

A PRD covers what you're building and why. A software design document covers how you'll build it. The PRD comes first.

Write, Review, and Approve Your Software Design Document in One Place

A design document is a place to disagree before the code exists. It works best when the disagreement happens on the page, next to the text it's about. Docmost has inline comments and page history built in, so your team can review a design on the page and see what changed.

Get a free trial license or contact sales to try it with your own team.