Design Docs, RFCs & PRDs

How to write technical proposals in English (用英文写技术提案、设计文档、RFC、PRD)

Why Writing Matters Most for Senior IC Growth (写作为什么对资深 IC 成长最关键)

In Western tech, the design doc is the medium of senior engineering. You influence beyond your team by writing clearly, not by speaking loudly. Coding well gets you mid-level; writing well gets you to staff.

在西方科技公司，设计文档是资深工程的载体。你不是靠大声说话影响其他团队，而是靠写得清楚。写代码好让你到中级；写文档好让你到 staff。

The principle 原则: A great design doc lets a stranger from another team agree or disagree with your proposal in 5 minutes.

好的设计文档让其他团队的陌生人 5 分钟内能赞成或反对你的提案。

Standard Structure (标准结构)

Most companies' design docs follow some version of:

大多数公司的设计文档遵循以下结构的某个版本：

1. Title + metadata (author, status, reviewers, date)
2. TL;DR (one paragraph)
3. Background / Context
4. Goals / Non-goals
5. Proposal / Design
6. Alternatives considered
7. Tradeoffs / Risks
8. Open questions
9. Rollout plan
10. Appendix (optional)

Section-by-Section Templates (逐段模板)

TL;DR (太长不看)

3-5 sentences. The reader should be able to stop here and still know the answer.

3-5 句。读者读完这里就停下，也应该知道答案。

We propose moving the auth service from monolith → standalone service to 
unblock the mobile team's launch. Estimated 6 weeks, 2 engineers. Main 
tradeoff: short-term latency increase (~20ms) for long-term independence. 
Recommend approval to start in Q2.

Background / Context (背景)

Set the stage. Assume the reader hasn't been in your team's last 5 meetings.

铺垫。假设读者没参加你团队过去 5 次会议。

"Today, [system X] does [Y]. This worked when we had [N users / N teams]. Since then, [what changed]." — 现在，[系统 X] 做 [Y]。当我们有 [N 用户/N 团队] 时这没问题。但之后，[发生了什么变化]。
"The current setup has three problems: [list]." — 现有方案有三个问题：[列表]。
"This doc proposes how to solve [problem]." — 本文档提出如何解决 [问题]。

Goals / Non-goals (目标 / 非目标)

The non-goals section is more powerful than the goals section — it bounds the discussion.

非目标 章节比目标章节更有力——它限定了讨论范围。

Goals:
- Reduce auth latency p99 from 200ms to under 50ms
- Allow mobile team to deploy independently
- No regression in security posture

Non-goals:
- Re-architecting the user model (separate effort)
- Supporting [edge case X] in v1
- Cross-region replication (planned for next quarter)

Proposal / Design (提案 / 设计)

The meat. Show the reader exactly what will exist after this is built.

正文。让读者看到建成后到底会有什么。

"At a high level, we will..." — 整体上，我们会……
"The system has three components..." — 系统有三个组件……
"Here's the data flow:" — 数据流如下：(后跟图)
"[Diagram] shows how request X flows through the system." — [图] 展示请求 X 如何流经系统。

Use diagrams. Walls of text are skipped.

用图。一墙文字会被跳过。

Alternatives Considered (考虑过的备选方案)

Shows you did your homework. Builds trust.

显示你做了功课。建立信任。

Option A: Monolith with sharding
- Pros: Familiar, no new infra
- Cons: Doesn't unblock mobile team, hits limits in 6-12 months
- Why not chosen: Doesn't solve the real problem

Option B: Standalone service (recommended)
- Pros: Solves all 3 goals
- Cons: New ops surface, ~20ms latency cost
- Why chosen: Best long-term outcome despite cost

Option C: Buy a third-party service
- Pros: Fastest to ship
- Cons: $400k/year, vendor lock-in, security review burden
- Why not chosen: Cost and lock-in

Tradeoffs / Risks (取舍 / 风险)

Be honest. Hiding tradeoffs makes reviewers distrust the whole doc.

诚实。藏取舍会让评审者怀疑整篇文档。

"The main tradeoff is X for Y. We accept this because..." — 主要取舍是用 X 换 Y。我们接受是因为……
"Known risks: [list with severity and mitigation]." — 已知风险：[列表，含严重程度和缓解措施]。
"This will not address [thing]. We plan to revisit in [timeframe]." — 这不会解决 [某事]。我们计划 [时间] 再看。

Open Questions (待解决问题)

Things you genuinely don't know. Reviewers are invited to weigh in.

你确实不知道的事。邀请评审者发表意见。

"How should we handle [edge case]? Leaning toward X but want input." — 应该怎么处理 [边界情况]？倾向 X 但想听意见。
"Should we ship behind a feature flag? Pros and cons below — input welcome." — 应该用 feature flag 吗？下面是利弊——欢迎意见。

Rollout Plan (上线计划)

How will this actually go live?

具体怎么上线？

Phase 1 (Week 1-2): Build behind feature flag, internal testing
Phase 2 (Week 3): 1% of traffic, monitor latency and errors
Phase 3 (Week 4): Ramp to 50%, then 100%
Phase 4 (Week 5): Decommission old service

Rollback: Single feature flag flip restores old path within 30 seconds.

Monitoring: Dashboard at [link], alerts on error rate > 0.1% or p99 > 100ms.

Phrasing Patterns (常用表达)

Stating proposals (提出方案)

"We propose [X]." — 我们提议 [X]。
"This doc recommends [X]." — 本文档推荐 [X]。
"The approach is to [X]." — 思路是 [X]。

Stating reasoning (说明理由)

"The motivation is..." — 动机是……
"This is necessary because..." — 必要性在于……
"The key insight is..." — 关键洞察是……

Hedging where appropriate (适当弱化)

"This will likely..." — 这很可能……
"Our best estimate is..." — 我们的最佳估计是……
"Pending validation, we expect..." — 待验证，我们预期……

Inviting feedback (邀请反馈)

"Feedback welcome on [section]." — 欢迎对 [章节] 提意见。
"Reviewers: please weigh in on [open question]." — 评审者：请对 [待决问题] 发表意见。
"If you disagree with X, please comment by [date]." — 如果你不同意 X，请在 [日期] 前评论。

Marking decisions (标记决策)

"Decision: we will go with Option B." — 决定：选 Option B。
"Resolved: per discussion on [date], we'll defer cross-region to next quarter." — 已解决：根据 [日期] 的讨论，跨区域延后到下季度。

Writing for Different Doc Types (不同类型文档的写作)

Design Doc (设计文档)

For technical proposals where engineers will review and implement. Audience: engineers and tech leads. Focus: architecture, tradeoffs, implementation.

针对工程师评审和实施的技术提案。受众：工程师和 tech lead。重点：架构、取舍、实现。

RFC (Request for Comments)

For proposals that need cross-team input before commitment. Audience: broader engineering org. Focus: gathering opinions, building consensus.

需要在承诺前征求跨团队意见的提案。受众：更广的工程组织。重点：收集意见、达成共识。

Title prefix: "[RFC] Standardizing service naming"
Status: Draft → In Review → Accepted / Rejected → Implemented
Decision deadline: state explicitly ("Comments by [date]")

PRD (Product Requirements Doc)

For describing what to build (typically PM-authored, but engineers should read and push back). Audience: design, engineering, leadership. Focus: user problem, requirements, success metrics.

描述要做什么（通常 PM 写，但工程师该读并反推）。受众：设计、工程、领导层。重点：用户问题、需求、成功指标。

Sections often include:

Problem statement
User personas / use cases
Requirements (must-have / nice-to-have)
Success metrics
Out of scope

Postmortem (故障复盘)

After an incident. Blameless is the standard.

故障后。标准是无指责。

Summary: [1 sentence]
Impact: [users affected, duration, severity]
Root cause: [technical, not personal]
Timeline: [bullet by minute]
What went well:
What went poorly:
Action items: [owner + date for each]

Tone in Technical Writing (技术写作的语气)

Active over passive (主动 > 被动)

❌ "It was decided that the service should be split." — 谁决定的？ ✅ "We decided to split the service." — 清楚。

Specific over vague (具体 > 模糊)

❌ "The system might have some performance issues." — 多严重？ ✅ "p99 latency exceeds SLO during peak (450ms vs. 200ms target)." — 量化。

Concise over verbose (简洁 > 啰嗦)

❌ "It is important to note that we should consider the possibility that..." — 砍掉。 ✅ "We may also need to..." — 直接。

Confident, not arrogant (自信，但不傲慢)

❌ "This is obviously the right answer." — 居高临下。 ✅ "We recommend X because [reasons]. Open to alternatives if [conditions]." — 自信但开放。

Reviewing Others' Docs (评审别人的文档)

Comment styles (评论风格)

"Nit:" — Small style issue. Not blocking. (nit = nitpick)
"Question:" — Genuine question, not disagreement.
"Suggestion:" — Optional change.
"Concern:" — Significant issue, would like to discuss.
"Blocker:" — Won't approve until resolved.

Match severity to label.

按严重程度选标签。

Useful comments (有用的评论)

"Have you considered [alternative]?" — 你考虑过 [备选] 吗？
"What happens if [edge case]?" — 如果 [边界情况] 怎么办？
"Worth calling out the dependency on [team]." — 值得点出对 [团队] 的依赖。
"Strong agree — and I'd add [point]." — 强烈同意——再补充 [点]。
"Resolved — thanks for the explanation." — 解决了——谢谢解释。(对话结束时)

Phrases to Avoid (要避免的表达)

❌ Avoid (避免)	Why (原因)	✅ Better (更好)
"Obviously..."	让别人觉得自己笨	(just state it)
"It's clear that..."	同上	"We believe..." or just state.
"In my humble opinion..."	假谦虚	"I recommend..."
"This is the only way."	拒绝考虑替代方案	"This is our recommended approach because..."
Wall of text with no headers	没人会读完	Headers, bullets, diagrams.

Lead with the answer — TL;DR is non-negotiable. Most readers stop there. 答案先行。
Write the goals/non-goals first — They constrain the rest of the doc. 先写目标和非目标。
One doc, one decision — Don't bundle 3 proposals in one doc. 一文档一决策。
Set a comment deadline — "Please comment by Friday EOD" prevents docs lingering forever. 设评论截止日期。
Read your doc out loud — You'll catch convoluted sentences. 大声读一遍。
Diagrams over prose — A picture is worth 500 words. 图胜过文字。