writing-design-docs

编写设计文档

必备背景： technical-writing 技能（先阅读、硬性规则、真实性规则、风格）。

概述

设计文档是一份可供讨论的提案：结论先行，每项重要选择都放入 Why & What 框中，在列出收益的同时说明成本，并将事实与提案分开。

何时调用，何时不调用

对于任何论证变更或记录设计的内容，都调用此技能：提案、RFC、设计文档、规范、迁移计划、“是否应该……”文档。对于记录已作出的决定（recording-decisions）、编写操作流程（writing-runbooks）或状态报告，则不要调用。

时间紧迫时：提案要用数据和明确列出的成本来说服读者；无论截止时间如何，文风规则都必须遵守（technical-writing 规则；“有力简洁”不能成为例外）。如果收到的事实没有来源，就将其标记为 **[source wanted: ...]** 并继续写作（参见 technical-writing 技能中的 references/truth.md）；绝不要编造引用，也不要悄悄删掉事实。

框架

# Title: what the document does

**Subtitle pinning the scope in one sentence**

|                |                                            |
| -------------- | ------------------------------------------ |
| **Status**     | Draft / 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
[The conclusion immediately. Not the occasion, not the method.]

## 2. [Context / what was analyzed]
## 3. [The analysis, split per question]
## n. Open questions
## n+1. Benefits and costs
[Both. Benefits alone reads as a sales pitch.]
## n+2. Residual risks and what not to do
[Only when the design hands work to other teams.]

---

*Closing line: which parts are fact and which are proposal, and where input is wanted.*

结构规则

• 为章节编号，并使用 ch. 7.1 的格式引用章节。
• 同时列出目标和非目标。 非目标（或“明确不变的内容”）部分要说明哪些内容保持不变。
• 先定义，再描述行为：术语含义不明确时，应先明确“已响应”“符合条件”“过时”等词的含义，再使用它们。
• 设置依据部分，明确设计所依据的事实：列出事实与来源的表格，并根据指定的提交进行核验。将已验证的事实与计划构建的内容分开。
• 附录使用字母编号（附录 A、B），收录可能淹没正文的内容：配置示例、术语表、清单。
• 一项事实只在一处出现。 链接到事实所在处；绝不要重复，即使是在同一仓库的不同文档中也不例外。
• 未完成的部分标记为 **[DRAFT - input wanted]**，不要省略。
• 为待解决的问题指定负责人：具体姓名、职责，或明确写上“待填写”。
• **若设计会将工作交给他人，**就在文档末尾写明遗留风险和不该采取的做法。
• 不设行数限制，但应删除因重复或强调而产生的冗长内容；超过约 800 行时，应拆分文档，并在主文档中链接到各个部分。

Why & What 框

每项重要选择都要配一个框；读者会针对框作出反应，而非针对结论。

> **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]

• 如果驳回某个替代方案时没有提及它最有力的论据，那就是稻草人论证。请明确写出该论据。
• 承认这一选择无法解决的问题，会让文档更可信。
• 不会有人反对的选择无需配框；那只是噪音。
• 文档其他地方完全没有提及的替代方案，不应出现在框中：读者根本不会考虑它。驳回一个这样的方案尚可自圆其说；连续出现多个简短的驳回理由，则说明框中的内容是在凑数。

语气

• 文档始终应保持提案的口吻：“我们提议”以及“是否信服由你决定”，而不是“这将成为我们的工作方式”。文档确定方向，同时为详细选择留出空间。
• 明确说明成本。收益章节的结尾要写明代价：哪些事情会变难，人们必须放弃哪些旧习惯，哪些自由会消失。
• 不用最高级表述或承诺性措辞。使用具体数据和可验证的陈述。
• 预期结果可能是负面的；应开门见山：“预期结果是，现有队列的表现优于提议的重写方案；这是一个有价值的结果。”

完整性检查

在将规范或计划交给审阅者或执行者之前，检查以下五类模糊缺陷：

1. 未解决的占位内容：任何字面上的 TBD、TODO、“稍后填写”或明显不完整的句子（标记为 **[DRAFT - input wanted]** 的区块是有意为之；未标记的缺漏则是缺陷）。
2. 缺少验收标准：没有具体且可独立测试的成功条件的要求。
3. 未定义的引用：提及了某个类型、端点、组件或表格，却没有在任何地方定义。
4. 没有可验证的产出：任务没有产生审阅者可检查的内容（没有文件路径、命令或可观察行为）。
5. 只说做什么，不说怎么做：只描述结果，却没有可实施的指引（例如“妥善处理错误”，却没有定义何为妥善）。

对于执行计划，每项任务都要补充：目标、确切文件、要展示的更改、包含具体场景的测试，以及验证命令。对于任何令人困惑的遗留内容（例如奇怪的目录名、旧版别名），都要加以说明，不要让它令人费解。