How to Write an Engineering Design Document

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:

1. What problem are we solving?
2. What are we proposing to build, and why?
3. 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.

Navigating Nuance: Precision in Professional English

Writing an Engineering Design Document (EDD) isn’t just about outlining a technical solution; it’s about communicating that solution clearly and effectively to your team. For non-native English speakers, this can feel particularly challenging, not only due to the specialized vocabulary but also the subtle nuances of professional phrasing. Let’s be honest – even native speakers sometimes struggle with conveying precisely what they mean in a way that avoids ambiguity. A well-crafted EDD is a key indicator of your understanding and ability to collaborate effectively.

One common area where confusion arises is around expressing degrees of certainty or potential risk. Instead of simply stating “This will work,” which can sound overly confident, consider phrases like “We anticipate this approach will function reliably” or “Based on initial testing, we believe this solution offers a high probability of success.” The latter acknowledges that there’s always some uncertainty and demonstrates a thoughtful assessment. Similarly, when describing potential drawbacks, avoid overly negative language. “This component might experience performance limitations under heavy load” is far more constructive than “This component will break.” Notice the shift from a declarative statement to an observation grounded in anticipated circumstances.

Another frequent challenge involves requesting clarification or raising concerns. A direct, perhaps slightly blunt, question like “Why did you do this?” can be perceived negatively, even if it’s intended constructively. Instead, frame your inquiry with phrases such as “Could you elaborate on the rationale behind [specific design choice]? I’d like to ensure we fully understand the context.” Or, when offering a suggestion for improvement, use phrasing like “It might be beneficial to consider…”, allowing others to explore the idea without feeling immediately challenged. You’ll also notice the inclusion of “I” – taking ownership of your thought process is crucial in professional communication.

Finally, pay close attention to the structure of sentences and how you express alternatives considered. Rather than saying “We didn’t use X,” which can sound dismissive, try “While we evaluated [X], we ultimately decided against its implementation due to [specific reason].” This demonstrates a deliberate decision-making process. Remember, clarity and respect are paramount – even when pointing out potential issues, always frame them within the context of collaborative problem-solving. Your EDD should demonstrate not just your technical skills but also your ability to communicate effectively as part of a team.