Technical Spec Template: Write a Spec Engineers Actually Read
A copyable technical spec template, the design-doc and RFC practices it borrows from, and a step-by-step method for writing a spec engineers read to the end.
Share
A technical spec template should put the risky decisions on page one: the problem and its constraints, the proposed design, the alternatives you rejected, and what could go wrong, in one to three pages for most changes. Google's design docs and Uber's RFCs follow this shape. The copyable template below adds a one-sentence summary and a decision table so reviewers find the hard calls in under a minute.
Key takeaways
Google's design docs have five core sections and run 10 to 20 pages for large projects, but 1 to 3 pages for incremental work (Malte Ubl, 2020).
Readers get through about 20% of the words on an average web page, and at most 28% (Nielsen Norman Group, 2008). Specs are read the same way: scanned for the parts that might be wrong.
61% of developers spend more than 30 minutes a day searching for answers (Stack Overflow, 2024). A spec that records decisions answers those questions once.
Teams with high-quality documentation are 3.8 times more likely to implement security best practices (DORA, 2021).
"Alternatives considered" is the section reviewers trust most, because it shows you looked for a reason not to build it this way.
What is a technical spec, and how is it different from a PRD?
A technical spec (also called a design doc or technical design document) explains how a team will build something and which trade-offs it is accepting. A PRD explains what problem is worth solving, for whom, and how success will be measured. The PRD comes first; the technical spec answers it.
Teams use four related documents. Mixing them up is the most common reason a spec grows to 15 pages nobody finishes.
Document
Question it answers
Usual owner
Typical length
PRD
What problem, for whom, and how will we know it worked?
How will we build it, and what are we trading off?
Tech lead or engineer
1–3 pages (10–20 for large systems)
RFC (request for comments)
Does the wider org agree with this plan before work starts?
Author plus named approvers
Same as a spec, with a review deadline
ADR (architecture decision record)
Why did we make this one decision, and what follows from it?
Engineer who made the call
1–2 pages
Google's guidance describes the design doc as the place to document high-level implementation strategy and key design decisions, with an emphasis on trade-offs. Michael Nygard's ADR format, published in 2011, narrows that to a single decision with five parts: title, context, decision, status and consequences (Michael Nygard, 2011). If you want the product side first, start with the guide to writing a PRD.
Why do engineers skip most technical specs?
Engineers skip specs that answer questions nobody asked and hide the ones that matter. Three patterns cause most of it.
They are written for completeness, not decisions. Jakob Nielsen's 2008 analysis found that on an average 593-word page, readers had time for at most 28% of the words, and 20% was more likely. Readers only got through half the content on pages of 111 words or fewer. A reviewer with six specs in their queue reads the same way: summary, diagram, bold text, then the section they disagree with.
They hide the risky call in even prose. If the irreversible decision sits in paragraph nine, every reviewer has to re-derive it. That is the waste a spec is supposed to prevent.
They go stale. The 2024 Stack Overflow Developer Survey found that 61% of respondents spend more than 30 minutes a day searching for answers, and 30% say knowledge silos hurt their productivity 10 or more times a week. A spec that stops matching the code becomes one more source of wrong answers.
The payoff for getting this right is measurable. DORA's 2021 research found teams with high-quality documentation were 3.8 times more likely to implement security best practices and 2.5 times more likely to use the cloud to its full potential.
What should a technical spec include?
Include only what changes how someone would build or review the work. Two published practices give a good baseline.
Google's design doc sections
Malte Ubl's 2020 write-up of design docs at Google lists the sections most docs share:
Context and scope: the environment the system lives in, in a few paragraphs.
Goals and non-goals: what the system must do, and what it explicitly won't.
The actual design: system diagram, APIs, data storage, and code or pseudo-code only where it clarifies a novel algorithm.
Alternatives considered: other designs and why they lost.
Cross-cutting concerns: security, privacy and observability.
Uber's RFC sections
Uber's RFC process grew with the company from tens of engineers to a couple of thousand, according to Gergely Orosz, who worked there (The Pragmatic Engineer, 2018). Its backend template opened with a list of approvers, then covered architecture changes, service SLAs, dependencies, load testing, multi-data-centre concerns, security, testing and rollout, metrics and monitoring, and customer support. The mobile template added UI and accessibility. Sections were added as the company learned what it kept missing.
The lesson from both: a technical spec template is a checklist of past mistakes. Start small and add a section only when its absence has caused a real problem.
Technical spec template (copy and adapt)
This technical spec template combines Google's sections, Uber's approvers-first habit and Nygard's decision format. Delete any section that would say "N/A".
# [Feature or system name]: technical spec
**Summary:** We are doing [X] to achieve [Y], accepting the trade-off of [Z].
**Author:** [name] · **Approvers:** [2–3 names] · **Review by:** [date]
**Status:** Draft | In review | Approved | Superseded by [link]
**Linked PRD / ticket:** [link]
## 1. Problem and constraints
- What is broken, who feels it, and what becomes possible once it is fixed.
- Hard constraints: latency budget, data residency, backwards
compatibility, the SLA you cannot break.
## 2. Goals and non-goals
- Goals (measurable where possible).
- Non-goals: things a reasonable reader might expect, that we won't do.
## 3. Key decisions (read this first)
| # | Decision | Reversible? | Risk if wrong | Confidence |
|---|----------|-------------|---------------|------------|
| 1 | | One-way / two-way door | | High / Med / Low |
## 4. Proposed design
- One diagram. APIs and data model changes. Pseudo-code only for
anything novel.
## 5. Alternatives considered
- Option A: why it lost.
- Option B: why it lost.
- Do nothing: what happens if we don't build this.
## 6. Risks and open questions
- Load-bearing assumptions and how we will check them.
- Questions we need answered before or during the build.
## 7. Cross-cutting concerns
- Security and privacy · Observability · Accessibility · Cost.
## 8. Rollout, validation and rollback
- Feature flag / staged rollout plan.
- Metrics that prove it works, and the threshold that triggers rollback.
## 9. Decision log
- [date] Changed [decision] because [reason]. (Update here, not in a PR comment.)
The decision table in section 3 is the part that earns the template its keep. Marking each decision as a one-way or two-way door tells reviewers where to spend their attention. The reversible versus irreversible decisions framework explains how to judge which is which.
How long should a technical spec be?
As short as the riskiest decision allows. Google's guidance puts large-project design docs at around 10 to 20 pages and treats 1 to 3 page "mini design docs" as fine for incremental work. Nygard's ADRs are one or two pages. Amazon replaces slides with "narratively structured six-page memos", read silently at the start of each meeting, and Jeff Bezos wrote that a great one probably takes a week or more to write (Amazon, 2018).
A practical rule of thumb, by size of change:
Change
Format
Length
Review
Bug fix, copy change, config tweak
Ticket description
A paragraph
Code review only
New endpoint or component inside one service
Mini spec
1 page
One approver, async
Feature touching 2–3 services or a public API
Technical spec (template above)
2–3 pages
2–3 approvers, 2–3 day window
New system, data migration, or security boundary
Full design doc or RFC
5–20 pages
Formal review meeting
Google's guidance also says when not to write one: when the solution is unambiguous and the doc would only be an implementation manual with no trade-offs to discuss.
How do you write a spec engineers actually read?
Write it in this order. Most of the work is deciding what to leave out.
Write the one-sentence summary first. "We are doing X to achieve Y, accepting the trade-off of Z." If you cannot write it, you are not ready to write the spec, and your reviewers will not be able to summarise it either.
Open with the problem, not the solution. Engineers cannot judge a design until they know the constraints it serves. State the non-negotiables before the architecture diagram.
Fill in the decision table. List every decision a reviewer could reasonably disagree with. Bold the one-way doors.
Write the alternatives honestly. Include "do nothing". A spec with no rejected options reads as a decision already made.
Name two or three approvers and a review deadline. Uber listed approvers at the top of every RFC. A spec without a decider and a date tends to sit in review indefinitely.
Review asynchronously, meet only on disagreements. Comments on the doc handle most feedback. If you do meet, copy Amazon and give the first ten minutes to silent reading.
Update the spec when the build changes it. Google's lifecycle treats the doc as something you revise during implementation. Record changes in the decision log, not in a pull-request comment nobody will find.
Orosz notes that once a team agrees on a plan, writing it up usually takes a few hours. If it takes days, the disagreement is the finding.
Worked example (illustrative)
Say a six-person team needs to stop slow customer webhooks from timing out checkout. Their summary line: "We are moving webhook delivery onto a queue so checkout never waits on a customer's server, accepting up to 60 seconds of delivery delay."
#
Decision
Reversible?
Risk if wrong
Confidence
1
Switch to at-least-once delivery; customers must de-duplicate by event ID
One-way door (public contract)
Duplicate orders on customer systems
Medium
2
Use the existing Postgres database as the queue instead of a new broker
Two-way door
Throughput ceiling at peak; migrate later
High
3
Retry five times over 24 hours, then mark as failed
Two-way door
Some customers miss events during long outages
High
Reviewers can see in 30 seconds that decision 1 deserves the debate: it changes a public API contract, needs a migration note for customers, and cannot be quietly undone. Decisions 2 and 3 can be approved in a comment.
What are the common mistakes with technical specs?
Writing the spec after the code. A spec written to justify a finished pull request has no alternatives and catches nothing.
Five diagrams instead of one. One system diagram with the change highlighted beats five that show everything.
Treating the template as a form. Empty "N/A" sections teach readers to skim. Delete them.
No owner for open questions. Every open question needs a name and a date, or it becomes a production incident.
Freezing the document. A spec that stops matching the build is worse than no spec, because people trust it.
Using a spec where a prototype would answer faster. If the risky question is "will this library handle our load?", a one-day spike beats a five-page argument.
How do technical specs change with AI coding agents?
Coding agents read specs literally. Ambiguity a human engineer would resolve in Slack becomes code an agent confidently writes wrong. The parts of the template that matter most for an agent are the non-goals, the constraints and testable acceptance criteria. The AI coding-agent PRD template shows how to make those explicit. Once the spec is approved, breaking the PRD into user stories is the next step, and a launch pre-mortem stress-tests the rollout plan before release.
Where does Specky fit?
The gap between documented intent and shipped reality usually opens when requirements, decisions and tickets live in different tools. Specky drafts PRDs in an editor with inline citations back to the customer evidence, generates tickets with testable acceptance criteria, and records decisions in a Product Graph so the "why" stays attached to the work. Coding agents can read that context through an MCP server. The engineer still writes the technical design; the product context around it stays current. If finding time to write is the bottleneck, the example PM weekly schedule protects a focus block for it.
Frequently asked questions
What is the difference between a PRD and a technical spec?
A PRD defines the problem, the users, and how success will be measured; a technical spec defines how the team will build the solution and which trade-offs it accepts. The product manager usually owns the PRD and the tech lead owns the spec. Write the PRD first, then link it from the spec so reviewers can check the design against the original goal.
Who should write the technical spec?
The engineer or tech lead who will own the build should write the technical spec, with the product manager reviewing it against the PRD. The author is accountable for the decisions, not for typing every section. On a small team, the PM can draft the problem, goals and non-goals sections, and the engineer completes the design, alternatives and rollout plan.
How long should a technical design document be?
Most technical design documents should be one to three pages. Google's practice treats 1 to 3 page mini design docs as normal for incremental changes and reserves 10 to 20 pages for large new systems. If your spec runs longer than three pages for a feature inside existing services, it probably mixes several decisions that should be separate ADRs.
What is an RFC in software engineering?
An RFC (request for comments) is a written plan shared with the wider engineering organisation before work begins, so others can flag risks. Uber used RFCs as it grew from tens to a couple of thousand engineers, listing named approvers at the top of each one. An RFC is a technical spec plus a review process, a deadline and a decider.
When should you not write a technical spec?
Skip the spec when the solution is unambiguous and there are no meaningful trade-offs to discuss, which is the line Google's guidance draws. Bug fixes, small UI changes and configuration updates belong in a ticket. If the main uncertainty is technical feasibility, run a time-boxed spike first and write the spec once you know what works.
What is an architecture decision record (ADR)?
An ADR is a one- or two-page record of a single architecture decision. Michael Nygard's 2011 format has five parts: title, context, decision, status and consequences. Many teams keep ADRs in the code repository, so future engineers can see why something was built a certain way. Use ADRs for decisions that outlive a single spec.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing