如何写出清晰的文档？
Filed under 软件架构, 软件工程 on 2025年8月18日. Last updated on 2025年8月18日.
toc
引言
在本文中，我将分享关于如何写出一份清晰文档的思考。你可以先关注核心要点，这些是整篇文档中最重要的内容。接着，我会进一步解释这些要点背后的原因和细节。
核心要点
-
闭环 What -> Why -> How 的逻辑链条
- What：要解决的问题或目标
- Why：动机、原因
- How：解决方案
-
用多维度构建文档结构
- 受众（Audiences）：文档的读者
- C4 模型
首先，从问题（目标）和受众开始：明确我们要达成的目标，以及谁想要实现它。这是第一个 What（目标） 和第一个 维度（受众）。
接着，阐述 What -> Why -> How。定义完第一个 What 之后，继续讲清楚背后的动机和因果逻辑，最后提出解决方案，并解释该如何落地。这是第一个 Why（动机） 和第一个 How（解决方案）。
在 第一个 How 中，一定会有更多细节需要说明，因此你可以开始进入下一轮的 What -> Why -> How 的循环。不断细化和迭代文档内容，直到你满意为止。
对于文档的结构维度来说，受众和 C4 模型是默认应该考虑的两个维度。你也可以根据需要增加更多维度。
什么是清晰的文档？
在我的日常工作中，我看到过很多难以阅读的文档；也有一些非常清晰的好例子（例如 Django 文档）。我希望对比它们，找出差异。
| 方面 | 糟糕的情况 | 优秀的表现 |
|---|---|---|
| 目标 | 目标不明确；作者自己都不清楚想传达什么；与相关方未对齐。 | 开头明确指出；所有人都理解文档的意义和预期结果。 |
| 受众 | 不清楚写给谁；读者无法判断是否与自己相关，容易忽略。 | 针对不同角色（同事、管理层、自我）有明确设计；读者能快速找到对自己有用的内容。 |
| 结构 | 内容线性堆砌、没有层次；阅读困难；抓不住重点。 | 按层次组织：摘要 → 推理链路 → 执行细节；读者可以“按层消费”。 |
| 逻辑 | 强行线性表达复杂逻辑；因果链条缺失；可能出现矛盾。 | 使用因果图或推理链展现决策流程；逻辑清晰、自洽、便于复查。 |
| 动机（Why） | 过度强调 How；缺乏 Why；执行细节很多但方向模糊。 | 每一层都遵循 What → Why → How，确保目标与方法对齐。 |
| 重点聚焦 | 信息过载；无主次之分；导致读者 TL;DR（太长不读）。 | 控制信息密度：先给出关键结论，再补充细节；降低阅读和决策成本。 |
解决方案路径
- 练习 What -> Why -> How 的思维闭环。
- 使用 C4 模型来可视化文档结构。
- 考虑受众和多维度的表达方式。
- 受众：同事、管理者、自我
- 职级 * 技术栈：（初级、高级、管理者等）*（前端、后端、移动端等）
- 技术方面：（架构、设计、基础设施、安全等）
- ...
结语
我相信不清晰的文档往往反映了不清晰的思维。因此，每当我看到一份模糊的文档，我会尝试找出根本原因，进而改善我的思维方式。我也坚信，清晰的思维才能带来清晰的文档、清晰的代码，以及清晰的表达。
不光是文档，我们的代码、项目管理等各个方面，都会遇到类似的总分结构。如同笛卡尔在《谈谈方法》中描述的研究问题的四个步骤，我们需要时常练习怀疑、分解、分析、验证的流程，以此不断打磨我们的思想。