How to Write an Engineering Design Document
Structure and English language for writing clear engineering design documents — problem statement, proposed solution, alternatives considered, and open questions.
An engineering design document (also called a technical design doc, RFC, or one-pager depending on the organisation) is a written proposal that describes a technical problem and a proposed solution before implementation begins. A good design doc aligns the team, surfaces risks early, and creates a written record of decisions.
For non-native English speakers, design docs are an excellent opportunity to demonstrate technical depth and clear thinking. This guide gives you the structure and language to write one confidently.
Why Design Documents Matter
Before writing code, engineers at most mature organisations write a document that answers three questions:
- What problem are we solving?
- What are we proposing to build, and why?
- What did we consider and reject, and why?
The goal is not bureaucracy — it is alignment. A design doc forces you to think through your proposal before committing to it, and it gives teammates a chance to spot issues you may have missed.
Standard Structure of a Design Document
1. Title and Metadata
Every design doc should have a clear title, author, date, and status.
“Title: Migrating Session Storage from Redis to DynamoDB” “Author: [Name] | Date: 2026-06-14 | Status: Draft / In Review / Approved”
2. Summary (TL;DR)
Write two to four sentences that capture the entire proposal. If someone only reads this section, they should understand the key decision.
“This document proposes migrating our user session storage from Redis to DynamoDB. The current Redis cluster requires manual scaling and has caused two availability incidents this quarter. DynamoDB offers serverless scaling and a managed availability SLA. We estimate a two-sprint implementation with no changes to the API contract.”
3. Problem Statement
Describe the current situation and why it is a problem. Be specific.
“Our Redis session cluster currently requires manual capacity planning. As of Q1 2026, we have experienced two incidents related to memory exhaustion during traffic spikes. Each incident required on-call intervention and caused between 15 and 40 minutes of degraded user experience.”
“The current architecture does not meet our 99.9% availability target for the session service.”
4. Goals and Non-Goals
List what this proposal will and will not address. Non-goals prevent scope creep.
“Goals: Eliminate manual Redis scaling; reduce session-related incidents; maintain sub-5ms session read latency.”
“Non-goals: This proposal does not address the caching layer for product data, which is a separate system.”
5. Proposed Solution
This is the core of the document. Describe what you plan to build.
“We propose replacing the Redis session store with Amazon DynamoDB, using a single-table design with a TTL attribute to expire sessions automatically. The session service interface will remain unchanged — this migration will be entirely internal to the service.”
“Key design decisions: (1) We will use DynamoDB’s on-demand capacity mode to eliminate manual scaling. (2) Sessions will be stored with a 30-day TTL, matching the current Redis configuration. (3) We will use the AWS SDK v3 to integrate with DynamoDB.”
6. Alternatives Considered
This section shows intellectual honesty and thorough thinking.
“Option A: Increase Redis capacity. We could add nodes to the existing cluster. This addresses the immediate capacity problem but does not eliminate the need for manual scaling or reduce operational burden. Rejected because it does not solve the root cause.”
“Option B: Use ElastiCache for Redis. Managed Redis would reduce operational overhead. However, it is more expensive than DynamoDB at our current scale and does not offer the same serverless scaling model. Considered but not recommended at this time.”
7. Open Questions
List anything that needs to be resolved before or during implementation.
“1. Does the security team need to review the DynamoDB IAM policy before we begin implementation?”
“2. What is the rollback plan if DynamoDB latency exceeds our 5ms target under production load?“
8. Implementation Plan
A high-level phased plan with rough timelines.
“Phase 1 (Sprint 1): Implement DynamoDB integration behind a feature flag. Run both stores in parallel for read validation. Phase 2 (Sprint 2): Gradually migrate write traffic to DynamoDB. Decommission Redis after 100% traffic cutover and a one-week monitoring period.”
Useful Phrases for Design Documents
Stating the Problem
- “The current implementation suffers from…”
- “This approach does not scale because…”
- “We have observed the following pattern over the past [time period]:…”
Proposing Solutions
- “We propose [X] because it directly addresses [Y].”
- “This design decouples [A] from [B], which allows independent scaling.”
- “The proposed approach has the following advantages over the current state:…”
Documenting Trade-offs
- “The main trade-off is [X] versus [Y].”
- “This approach adds complexity in [area] but reduces complexity in [other area].”
- “We accept the [risk/cost] because [reason].”
Writing a design document is a skill that improves with practice. The best design docs are direct, specific, and honest about uncertainty. Start with the problem statement — if you can write that clearly, the rest of the document will follow naturally.