Back to Details

writing-design-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing design docs

撰写设计文档

REQUIRED BACKGROUND: the 
technical-writing
skill (read-first, hard rules, truth rules, style).
必备背景知识：
technical-writing
技能（需优先阅读，包含硬性规则、真实性规则及写作风格相关内容）。

Overview

概述

A design document is a proposal made discussable. Conclusion first, every non-trivial choice in a Why & What box, costs named next to benefits, and fact separated from proposal.
设计文档是一份可供讨论的提案。需先给出结论，所有重要决策均放入Why & What框中，同时列明收益与成本，区分事实与提案内容。

When to invoke, and not

适用场景与禁用场景

Invoke for anything that argues for a change or records a design: proposals, RFCs, design docs, specs, migration plans, "should we" documents. Do NOT invoke for recording an already-taken decision (
recording-decisions
), for procedures (
writing-runbooks
), or for status reports.
Steering under pressure: "management wants it punchy", "sell it", and deadlines do not relax the tone rules. A proposal persuades with its numbers and its named costs; the moment it reads as a pitch, it loses the reader this skill writes for. When supplied facts arrive without sources, mark them 
**[source wanted: ...]**
and keep writing (see 
references/truth.md
); never invent a citation and never silently drop the fact.
适用于所有论证变更或记录设计的文档：提案、RFC、设计文档、规范、迁移计划、“是否应该”类文档。请勿用于记录已做出的决策（对应
recording-decisions
技能）、操作流程（对应
writing-runbooks
技能）或状态报告。
应对压力场景：即使“管理层希望简洁有力”“需要推销方案”或面临截止日期，也不得放松写作风格规则。提案需通过数据和明确的成本来说服读者；一旦读起来像推销话术，就会失去本技能面向的受众。若提供的事实无来源，需标记为
**[source wanted: ...]**
并继续写作（详见
references/truth.md
）；切勿编造引用来源，也不得擅自删除该事实。

Skeleton

文档框架

markdown
undefined
markdown
undefined

Title: what the document does

标题：文档核心内容

Subtitle pinning the scope in one sentence
StatusDraft / Request for comments
Owner[team or role]
Scope[explicit, including what falls outside]
Related[links to sibling documents]
Audience[who must read this]
副标题：用一句话明确范围
状态草稿 / 征求意见稿
负责人[团队或角色]
范围[明确说明，包含不属于本范围的内容]
相关文档[关联文档链接]
受众[必须阅读本文档的人员]

1. Summary

1. 摘要

[The answer immediately. Not the occasion, not the method: the conclusion.]
[直接给出结论。无需说明背景或方法，只讲最终结论。]

2. [Context / what was analyzed]

2. [背景信息 / 分析对象]

3. [The analysis, split per question]

3. [分析内容，按问题拆分]

n. Open questions

n. 待解决问题

n+1. Benefits and costs

n+1. 收益与成本

[Both. A proposal that lists only benefits reads as a sales pitch.]
Closing line: which parts are fact and which are proposal, and where input is wanted.
undefined
[两者均需列明。只列收益的提案会显得像推销话术。]
结尾说明：哪些内容是事实，哪些是提案，以及需要读者提供意见的部分。
undefined

Structure rules

结构规则

  • Number chapters and cite them as 
    ch. 7.1
    . Numbers make feedback addressable: readers can point at one.
  • Goals and non-goals both. The non-goals (or "explicitly not changed") section is where scope creep dies in writing; it is the highest-leverage section in any spec. State what stays unchanged.
  • Definitions before behavior when a term is ambiguous: pin "responded", "eligible", "stale" before using them.
  • A grounding section pins the facts the design rests on: a fact/source table, checked against a named commit. Separate verified facts from what will be built.
  • Appendices take letters (Appendix A, B) and hold what would bury the main text: config examples, glossaries, inventories.
  • A fact lives in one place. Link to it; never repeat it, not even across documents in the same repo.
  • Mark unfinished parts with 
    **[DRAFT - input wanted]**
    instead of omitting them. Visibly unfinished beats invisibly missing.
  • Open questions get owners: a name, a role, or an explicit "to be filled by".
  • Residual risks and what NOT to do close the document when the design ships work to others.
  • No line budget, but length from repetition or emphasis goes; past roughly 800 lines, split and let the main document point.
  • 为章节编号，并以
    ch. 7.1
    的格式引用。编号便于反馈定位：读者可以直接指向具体章节。
  • 同时明确目标与非目标。非目标（或“明确不做变更”）部分是在书面上杜绝范围蔓延的关键；这是任何规范中影响力最大的部分。需说明哪些内容保持不变。
  • 术语定义优先于行为描述：若术语存在歧义，需先明确“响应”“符合条件”“过期”等术语的定义，再使用它们。
  • 添加事实依据部分：明确设计所基于的事实，可采用“事实/来源”表格，并关联具体提交记录。区分已验证的事实与待构建的内容。
  • 附录采用字母编号（附录A、B等），用于存放会干扰正文的内容：配置示例、术语表、清单等。
  • 事实内容仅存于一处。通过链接引用；切勿重复，即使是同一仓库中的其他文档也不行。
  • 标记未完成内容：使用
    **[DRAFT - input wanted]**
    标记，而非直接省略。可见的未完成内容比隐形的缺失内容更好。
  • 待解决问题需指定负责人：可以是姓名、角色，或明确标注“由XXX补充”。
  • 若设计需要交付给其他团队执行，文档结尾需列出剩余风险及禁止操作的内容。
  • 无行数限制，但需避免重复或冗余表述；文档长度超过约800行时，需拆分文档，主文档仅保留指向拆分文档的链接。

The Why & What box

Why & What决策框

Every non-trivial choice gets one. It makes a proposal discussable instead of announced: readers react to the box, not to the conclusion.
markdown
> **Why & What - [the choice in four words]**
>
> **What:** [the choice, one sentence, no justification]
>
> **Why:** [the reasoning. Also name what the choice does NOT solve.]
>
> **Alternatives considered:**
> - *[Alternative]:* [its strongest argument, and why it still lost]
>
> **Fallback:** [what survives if this does not work]
Rules for the box:
  • An alternative dismissed without its strongest argument is a strawman. Name that argument.
  • Admitting what the choice does not solve makes the document more credible, not weaker.
  • No box for choices nobody would contest; that is noise.
  • An alternative that appears nowhere else in the document does not belong in the box: such a rejection records what the writer once thought, while the reader would never consider the option. One can be right; several short ones in a row are a sign.
所有重要决策均需对应一个决策框。这能让提案从“告知”变为“可讨论”：读者针对决策框反馈，而非直接针对结论。
markdown
> **Why & What - [用四个字概括决策内容]**
>
> **What:** [决策内容，一句话，无需理由]
>
> **Why:** [决策理由。同时说明该决策无法解决的问题。]
>
> **已考虑的替代方案：**
> - *[替代方案]*：[该方案的核心优势，以及最终未选择它的原因]
>
> ** fallback方案：** [若该决策无效，可采用的备选方案]
决策框规则：
  • 若未提及替代方案的核心优势就否定它，属于稻草人谬误。必须明确该方案的核心优势。
  • 承认决策无法解决的问题，会提升文档可信度，而非削弱。
  • 无人会质疑的决策无需添加决策框，否则会造成冗余。
  • 若替代方案在文档其他部分完全未提及，则不应放入决策框：此类否定仅记录了作者曾考虑过的选项，而读者根本不会想到该选项。偶尔出现一次尚可，但连续出现多个则需警惕。

Tone

语气风格

  • It stays a proposal: "we propose" and "whether that convinces is up to you", not "this becomes the way of working". Broad lines give direction; the fill-in stays open.
  • Name what it costs. The benefits chapter ends with the price: what gets harder, what people must unlearn, which freedom disappears.
  • No superlatives, no promise language. Concrete figures and verifiable statements.
  • The expected outcome may be negative, and saying so up front is honest writing: "the expected outcome is that buy-and-hold wins; that is a useful result."
  • 始终保持提案的语气：使用“我们提议”“是否可行取决于您的判断”，而非“这将成为标准工作方式”。明确方向即可，细节部分保持开放。
  • 明确说明成本。收益章节结尾需列明代价：哪些操作会变难，哪些知识需要用户遗忘，哪些自由度会被限制。
  • 避免使用最高级或承诺性语言。采用具体数据和可验证的表述。
  • 预期结果可能是负面的，提前说明才是诚实的写作方式：“预期结果是持有策略胜出，这是一个有价值的结论。”

Completeness check

完整性检查

Before handing a spec or plan to a reviewer or executor, check the five vagueness defects:
  1. Unresolved placeholders: any literal TBD, TODO, "fill in later", or clearly incomplete sentence (a marked 
    [DRAFT - input wanted]
    block is deliberate; an unmarked gap is a defect).
  2. Missing acceptance criteria: a requirement with no concrete, independently testable success condition.
  3. Undefined references: a type, endpoint, component, or table mentioned but defined nowhere.
  4. No verifiable output: a task producing nothing a reviewer could inspect (no file path, no command, no observable behavior).
  5. What without how: an outcome with no implementable direction ("handle errors appropriately" with no definition of appropriate).
For execution plans, add per task: goal, exact files, the change shown, tests with concrete scenarios, and the verify command. Explain any confusing leftover (an odd directory name, a legacy alias) rather than leaving it puzzling.
在将规范或计划提交给评审者或执行者之前，需检查以下五类模糊缺陷：
  1. 未解决的占位符：任何字面意义上的TBD、TODO、“稍后补充”或明显不完整的句子（标记为
    [DRAFT - input wanted]
    的块是故意保留的，未标记的空白则属于缺陷）。
  2. 缺失验收标准：需求未包含具体、可独立验证的成功条件。
  3. 未定义的引用：提及了类型、端点、组件或表格，但未在任何地方定义。
  4. 无可验证输出：任务未产生评审者可检查的成果（无文件路径、无命令、无可观察行为）。
  5. 只有目标无方法：只给出结果，未提供可执行的方向（如“妥善处理错误”但未定义“妥善”的标准）。
对于执行计划，每个任务需补充：目标、具体文件、变更内容、包含具体场景的测试用例，以及验证命令。对于易混淆的遗留内容（如奇怪的目录名、旧别名），需加以解释，而非留待读者自行猜测。