Technical Design Doc Template

What's inside#

• A doc header block for title, owners, reviewers, status and decision deadline
• 14 sections, from Summary and Context through Rollout, Open questions and a Decision log
• Prompts in every section that tell you what to write and which questions to answer
• Fill-in tables for goals, requirements, alternatives, risks, capacity assumptions and rollout phases
• Back-of-the-envelope formulas for traffic, storage and cost
• A short worked example in each section, from one fictional project
• A one-page reviewer checklist

How to use it#

1. Copy the section headings into your team's doc tool (Google Docs, Notion, Confluence or a Markdown file in your repo).
2. Start with Context and Goals. If reviewers don't agree on the problem, the rest of the doc won't land.
3. Delete any section that doesn't apply, and say why in one line.
4. Write the Summary last, and keep it to five sentences.
5. Share it with reviewers along with the checklist on the last page, and set a decision date.
6. Keep the Decision log updated while you build.

Limitations#

• It's a starting structure, not a standard. Adapt it to how your team already reviews work.
• It's too heavy for small, easily reversible changes. A ticket or a pull request description is enough for those.
• The capacity formulas give rough estimates only. Use measured numbers from your own systems, and load-test before launch.
• The security section is a prompt list, not a security review. Changes that handle personal or payment data still need one.
• The examples come from a fictional project. Their numbers are illustrative, not benchmarks.

License

Free to use, share and adapt, including commercially, as long as you credit Letinix and link to this page. Licensed under CC BY 4.0.