09 模块化思维：每个章节是自洽的小宇宙

第二卷·心法篇第四章

一、同事要”截一段”的那次

去年有一次同事找我：“你那份’订单服务设计’能不能截一段出来？我要在另一个项目里引用’为什么用 PostgreSQL’那部分。”

我去翻文档，找到了那段关于 PostgreSQL 的论述——但我读了一遍发现：它读不通。

那段论述的第一句是”如上一节所述，MySQL 在高并发写场景下有明显瓶颈”，但读者没读过”上一节”，他不知道 MySQL 在高并发写场景下有什么瓶颈。

第二句是”对比之下，PostgreSQL 的 MVCC 机制能更好地处理写并发”，但读者不知道 MVCC 是什么、为什么它”更好”。

整段论述写得很详细，但它依赖”上一节”作为上下文——离开”上一节”，它读不通。

我同事要看”自洽的一段”，但我给他的是”流水账的一段”。

这件事让我意识到：好的文档应该让每个章节独立可读。读者从任何一节开始读，都能读懂——他不需要按顺序读完所有前置章节。

这就是模块化思维——每个章节是自洽的小宇宙。

这一章讲模块化。

二、模块化的两个核心特征

特征一：自洽。

一个章节是”自洽”的，意味着读者读这一节，他能独立理解——不需要回去读前面的章节。

具体说，一个自洽的章节应该：

核心论点显式：本节的核心判断在本节开头就讲出来。
关键术语交代：本节用到的术语在本节内一次性交代。
关键背景交代：本节依赖的背景信息在本节内交代或引用。

特征二：独立。

一个章节是”独立”的，意味着读者可以从任何一节开始读——不需要按顺序读完所有前置章节。

具体说，一个独立的章节应该：

不依赖前文：本节不引用”上一节我们讲过…”。如果必须引用，是显式引用——“在第 3 节我们讲过 X，这里接着讲 Y”。
不引用后续：本节不引用”后面会讲…”。如果必须引用，是显式引用——“完整的对比见附录 A”。

自洽和独立是模块化的两个核心。两者合起来就是”读者可以从任何一节开始读，每一节都能读懂”。

三、模块化的三个好处

模块化不只是”为了读者方便”——它有三个具体好处。

好处一：复用。

模块化的章节可以单独抽出来用。同事要引用你的某一段论述——他可以原样抽出来，不需要补充上下文。这意味着你的工作成果可以被团队复用——你写一次，全团队用。

好处二：重排。

模块化的章节可以重新排列。如果你某天发现文档结构不对，你想重新组织——模块化的章节可以自由调换顺序，不破坏每节的可读性。

好处三：维护。

模块化的章节可以独立维护。你某天想修改某节——你只需要改这一节，不需要担心”改了之后前面的章节会不会受影响”。

反过来——非模块化的文档不能复用、不能重排、不能独立维护。改一处，全文可能崩。

模块化是文档”工程化”的关键——它让你的文档像代码一样可复用、可重构、可维护。

四、模块化的反模式：顺序依赖

模块化的最大反模式是顺序依赖——章节之间互相依赖，必须按顺序读。

反模式一：依赖”上一节”。

“如上一节所述，MySQL 在高并发写场景下有明显瓶颈。”

读者没读过上一节，他不知道”MySQL 在高并发写场景下有什么瓶颈”。

正确做法：本节内交代关键背景——

“MySQL 在高并发写场景下有明显瓶颈（具体瓶颈见第 3 节）。对比之下，PostgreSQL 的 MVCC 机制能更好地处理写并发（MVCC 的解释见附录 A）。”

读者即使没读第 3 节，他也能从”具体瓶颈见第 3 节”这句话里知道”瓶颈在哪里、可以查哪里”。

反模式二：引用”后面”。

“完整的性能对比将在第 6 节详细讨论。”

读者读到第 5 节，他想知道”完整的对比是什么”——但他要等到读完第 6 节才知道。

正确做法：本节内给出”最小可用的结论”——

“综合测试结果显示，PostgreSQL 在我们的场景下性能更优（详细的对比数据见第 6 节）。”

读者即使没读第 6 节，他也能从”PostgreSQL 更优”这个结论开始判断。

反模式三：跨节重复。

我见过一个反例：作者在第 2 节讲了”PostgreSQL 的 MVCC 机制”，在第 5 节又讲了一遍”PostgreSQL 的 MVCC 机制”。读者不知道哪一节是”权威版本”。

正确做法：术语和概念集中在一节——首次出现时详细讲，后续章节引用那一节。

五、怎么写模块化文档

写模块化文档的四个步骤。

步骤一：把文档拆成”自洽单元”。

每一节是一个自洽单元——读者从这一节开始读也能读懂。

具体做法：写完一节后，假装读者是从这一节开始读的——他不知道前面讲了什么。读你的这一节，能读懂吗？

如果能——本节是自洽的。如果不能——补”本节内交代的关键背景”。

步骤二：段首句 = 核心论点 + 简短上下文。

每段的段首句不只是核心论点，还要包含”读者读这一段需要的最小上下文”。

反例：

MVCC 是 PostgreSQL 的核心机制。

读者读这句话，他不知道 MVCC 是什么、为什么是”核心”。

正例：

MVCC（Multi-Version Concurrency Control，多版本并发控制）是 PostgreSQL 的核心机制——它让多个事务同时读同一行数据时不互相阻塞。

读者读这句话，他立刻知道 MVCC 是什么、为什么是核心机制。

步骤三：段尾不依赖下一段。

一段的结尾不应该”勾引”读者读下一段——它应该总结本段，或者留下本段的判断。

反例：

接下来我们看 PostgreSQL 在我们场景下的具体表现。

这段结尾不”总结本段”，而是”预告下一段”。

正例：

在我们的场景下，PostgreSQL 的 MVCC 让写并发性能提升了 30%。下一步我们看具体的性能数据。

段尾总结本段（“性能提升 30%”），然后才预告下一段。

步骤四：必要术语一次性交代。

本节用到的术语，如果之前没讲过，就在本节内一次性交代——不要假设读者知道。

反例：

PostgreSQL 的 TOAST 机制解决了大字段存储问题。

读者不知道 TOAST 是什么。

正例：

PostgreSQL 的 TOAST（The Oversized-Attribute Storage Technique，超大属性存储技术）机制解决了大字段存储问题——它把超过 2KB 的字段自动存储到辅助表中，主表只存指针。

读者立刻知道 TOAST 是什么、解决了什么问题。

六、反例：流水账式文档

举一个反例，演示”流水账式”文档和”模块化”文档的差距。

反例：流水账式。

1. 项目背景
2. 现状
3. 问题
4. 方案对比
5. 推荐方案
6. 实施计划
7. 风险评估
8. 预期收益

八节，每节字数差不多。读者必须从第 1 节读到第 8 节才能理解整篇文档——因为每节都依赖前面讲过的内容。

如果读者只看第 5 节”推荐方案”，他不知道”推荐什么方案、为什么”。

正例：模块化。

1. 摘要（核心论点 + SCQA）
2. 现状分析（独立可读）
3. 问题诊断（独立可读）
4. 候选方案对比（独立可读）
5. 推荐方案（独立可读，但引用第 4 节）
6. 实施计划（独立可读）
7. 风险评估（独立可读）
8. 附录（详细数据、术语解释）

每一节独立可读——读者可以从任何一节开始读，都能读懂。

第 5 节”推荐方案”引用第 4 节——但显式引用（“在第 4 节我们对比了三个方案，这里我们推荐 X”），读者可以跳到第 4 节读，也可以从第 5 节直接读。

模块化文档 vs 流水账文档，本质区别是：

流水账：节与节强依赖，必须按顺序读。
模块化：节与节弱依赖，可以按任意顺序读。

模块化让读者可以”挑着读”——他只读他关心的章节，跳过他已经知道的章节。这是”工程化”文档的核心。

七、模块化和金字塔的关系

金字塔和模块化是互补的。

金字塔解决”判断 + 支撑”——文档要有一个核心论点，所有内容围绕核心论点展开。

模块化解决”独立可读”——每一节是自洽的，读者可以从任何一节开始读。

两者结合：

文档有清晰的核心论点（金字塔）。
每一节独立可读（模块化）。
读者可以从任何一节开始读——但每一节都服务于核心论点。

反例——只用金字塔不用模块化：

文档有核心论点，但每一节都依赖”前面讲过…”。
读者必须按顺序读。

反例——只用模块化不用金字塔：

每一节独立可读，但节与节之间没关系。
读者读完不知道”作者要说什么”。

两者合用，文档既”结构清晰”（金字塔）又”独立可读”（模块化）。

八、几个常见的”模块化破洞”

讲完模块化本身，再列几个常见的”模块化破洞”——这些破洞让你的文档”看起来模块化，实际不是”。

破洞一：术语没交代。

本节用到术语，假设读者已经知道——但读者可能没读过前面的章节，不知道这个术语。

破洞二：结论没在本节内给出。

本节只是”分析过程”，结论在下一节。读者读本节，他不知道”作者要说什么”。

破洞三：依赖图、表、附录，但没显式提示。

本节依赖一个图，但读者从本节开始读，他不知道图在哪。

正确做法：本节用到的图、表、附录要显式引用——“（见图 3.2）""（详见附录 A）”。

破洞四：节内引用了”前一节”或”后一节”。

“如前节所述，X 是好的。”

读者从本节开始读，他不知道”前节”讲了什么。

正确做法：本节内交代关键信息——把”前节”的核心内容复述一句。

破洞五：节标题和内容不匹配。

节标题是”性能分析”，但内容讲了”性能 + 可维护性 + 扩展性”三个主题。读者看标题以为只讲性能，读完发现讲了三个。

正确做法：节标题反映本节实际讲的内容。

九、心法：模块化是”工程化”的关键

讲到这里，把这一章的逻辑串成一条线。

模块化的本质是”工程化”——让文档像代码一样可复用、可重排、可维护。

读者读模块化文档，他可以从任何一节开始读——他不需要按顺序读所有前置章节。

写模块化文档的关键是：

段首句 = 核心论点 + 简短上下文。
段尾不依赖下一段。
必要术语一次性交代。
节内引用要显式（“见第 X 节”）。

模块化和金字塔互补——金字塔解决”判断 + 支撑”，模块化解决”独立可读”。

我自己的写作习惯（模块化版本）：

写完一节后做”自洽测试”——假装读者从这一节开始读，能读懂吗？
本节用到的术语，本节内交代。
本节用到的图表，本节内显式引用。
本节的核心论点，本节开头讲一次，结尾重复一次。

这个习惯让我的文档”可被同事截一段引用”——这是模块化最具体的检验。

下一章讲”删减的勇气：知道什么不要写”——模块化的下一个层次。读完你会知道为什么”写得长容易、写得短难”。

十、思考题

思考题 1：拿一份文档做”模块化体检”

找一份你最近写的 1500 字以上的文档。按以下步骤做模块化体检：

自洽测试：假装读者从第 3 节开始读，能读懂吗？
术语测试：本节用到的术语，本节内交代了吗？
图、表、附录引用测试：本节用到的图、表、附录，显式引用了吗？
节标题与内容匹配测试：节标题反映本节实际讲的内容吗？

写一篇 500 字的”模块化体检报告”，列出 3-5 个”模块化破洞”。

思考题 2：把一份”流水账”文档改写为”模块化”版本

找一份你最近写的”流水账”文档（节与节强依赖、必须按顺序读的）。按以下步骤改写：

列出每一节的”核心论点”——读者读这一节要带走什么判断？
列出每一节需要的”前置信息”——读者读这一节需要知道什么？
把”前置信息”内嵌到本节内，或者显式引用其他节。
重新检查每一节——从这一节开始读，能读懂吗？

写完之后做”自洽测试”：同事从任何一节开始读，他能读懂吗？

思考题 3：分析一份”模块化程度高”的文档

找一份你读过的”模块化程度高”的文档——比如某个开源项目的 README、某本技术手册。做一份”模块化分析”：

这份文档的”自洽单元”是什么？（节？子节？段落？）
这份文档怎么做到”从任何一节开始读都能读懂”？
这份文档的术语交代方式是什么？
这份文档”模块化”强在哪？

写一篇 500 字的分析。

参考答案

思考题 1 参考答案

大部分人做完这道题会发现：自己的文档有 3-5 个模块化破洞。

最常见的破洞：

术语没交代：用了术语没解释。
结论没在本节内给出：本节只是过程，结论在下一节。
节标题与内容不匹配：标题说讲 A，内容讲了 A + B + C。

改写方法：

术语没交代 → 本节内加一句解释。
结论没在本节内给出 → 把结论提到本节开头或结尾。
节标题与内容不匹配 → 改节标题或拆节。

我自己的经验：模块化体检每次都能找到 3-5 个破洞。这些破洞不影响你自己读（你已经知道），但影响别人读。

思考题 2 参考答案

大部分人改写后会发现：流水账文档改写为模块化版本，需要做大量”前置信息内嵌”。

最常见的改写动作：

把”如上一节所述”改成”X 是这样的”——把”上一节”的核心内容复述到本节。
把”详见第 X 节”改成”X 的关键点是 A、B、C”——把”第 X 节”的核心内容复述到本节。
把”图 3.2”显示的位置改成”如图 3.2 所示”——显式引用图。
把节标题改成”判断式”——读者扫标题就知道本节讲什么。

我自己的改稿习惯：改稿前先做”模块化体检”，列出 3-5 个破洞——然后按破洞清单逐项改写。

思考题 3 参考答案

“模块化程度高”的文档有四个共同点：

节标题是判断式。读者扫标题就知道本节讲什么。
段首句是核心论点。读者扫段首句就知道段内讲什么。
术语一次性交代。本节用到的术语，本节内讲清楚。
图表显式引用。本节用到的图表，本节内显式引用。

你的分析应该围绕这四点写（不一定全部涉及，但至少触及两点）。如果你读完只写得出”作者写得清楚”——回到这一章的核心：模块化的本质是让读者可以从任何一节开始读。

十一、动手练习

练习 1：给一份文档做模块化体检 + 改写

找一份你最近写的 1500 字以上的文档。按以下步骤做：

做模块化体检——列出 3-5 个破洞。
按破洞清单逐项改写。
改写后做”自洽测试”——从第 3 节开始读，能读懂吗？

写完之后发给同事，让他从第 3 节开始读，反馈”能不能读懂”。如果他说能——过关；如果他说不能——继续改写。

练习 2：把一份”流水账”文档改写为”模块化”版本

找一份你最近写的”流水账”文档。按以下步骤改写：

列出每一节的核心论点和前置信息。
把前置信息内嵌到本节内，或显式引用其他节。
节标题改成判断式。
做”自洽测试”——同事从任何一节开始读，能读懂吗？

写完之后自评：新版本能让同事从任何一节开始读吗？

自评标准

练习 1 自评标准：

找到至少 3 个破洞——过关。
改写后同事能从第 3 节开始读——硬性指标。

练习 2 自评标准：

同事能从任何一节开始读——硬性指标。
节标题是判断式——硬性指标。

十二、小结

这一章把”模块化思维”讲清楚了：

概念	一句话
自洽	读者读这一节能独立理解，不需要读前面的章节。
独立	读者可以从任何一节开始读。
三个好处	复用、重排、维护。
反模式	顺序依赖（依赖”上一节”、引用”后面”、跨节重复）。
写模块化的四个步骤	拆自洽单元、段首句 + 上下文、段尾不依赖下一段、术语一次性交代。
与金字塔的关系	金字塔解决”判断 + 支撑”，模块化解决”独立可读”。

模块化的本质是”工程化”——让文档像代码一样可复用、可重排、可维护。

读者从任何一节开始读，他都能读懂——这是模块化最具体的检验。