瀑布开发文档要写多少才算够

一、我为什么会在凌晨三点还在纠结一份需求规格说明书

上个月，一个银行客户的项目经理在群里发了一条消息：「这份SRS已经187页了，法务说还不够。」群里沉默了大概两分钟，我们的架构师回了一句让所有人破防的话：「我读了三遍，还是不知道这个转账功能在极端情况下应该返回什么错误码。」

这就是瀑布开发里最荒谬的现实：我们写了一百多页文档，但开发真正需要的那一行需求描述，埋在某个二级段落里，谁也没找到。我在软件工程这个行当干了14年，参与过军工、金融、电商、SaaS至少四个领域的瀑布项目，亲手写过、也亲手毙过无数份文档。每次有人问我「瀑布开发文档写到什么程度才算够」，我脑子里蹦出来的第一个答案从来不是页数，而是一个更让人难受的词：信任。

你不够信任下游能理解你的意图，所以你多写200页。法务不信任业务能说清楚边界，所以要求你再加50页附录。甲方不信任乙方能按时交付，所以把SRS签成一份准合同。文档在瀑布模型里的本质，从来就不是为了传递信息，至少大部分时候不是，它是为了降低组织间的信任摩擦成本。一旦你接受这个前提，你就会明白为什么「文档多少才算够」这个问题，根本不能用字数、页数、章节数来回答。

这篇文章是我14年瀑布文档血泪史的总结。我不会给你一个「SRS建议写80-120页」这种害人的数字，我会给你一套我反复验证过的判断框架，告诉你在什么情况下、面对什么角色、为了解决什么问题，你需要写什么类型的文档，以及写到什么深度就可以停笔。

二、先把一个核心结论拍在桌上

我在2019年接手过一个烂尾项目，前一个团队留下了整整4个G的文档，SVN仓库里光需求文档的版本就有217个。IT部门的人跟我说：「你放心，文档非常全。」我当时回了一句：「文档全和文档有用，是两个概念。」后来证明我说对了，我们花了6周才在那堆文档里找到一条关于数据库字符集的关键约束，而这个约束隐藏在某个非功能性需求文档的第83页的一条脚注里。

这件事让我形成了一个铁律般的判断：

瀑布文档写到「够」的唯一标准，不是覆盖度，是交付效率。具体说，就是下游角色拿着你的文档，能不能在不找你口头确认的前提下，完成他自己的那部分工作。如果能，够了。如果不能，哪怕你写了一千页，也不够。

这个标准听起来很简单，但它会推导出一系列反直觉的结论：

• 很多时候，「写少一点」反而比「写多一点」更接近「够了」。因为文档越长，关键信息被稀释得越厉害，下游找到它的概率越低。
• 同一份SRS，对前端够了，对后端可能完全不够。因为前端关心交互状态流转，后端关心数据一致性和异常路径，他们需要的信息类型完全不同。
• 有些文档根本不应该写，而应该被一个自动化测试用例替代。这是我在后面会详细展开的一个观点，它来自我这几年在持续集成和契约测试上的实操经验。

三、先搞清楚我们到底在讨论什么文档

很多关于瀑布文档的讨论一上来就跑偏，原因是大家脑子里的「文档」根本不是同一样东西。产品经理想的是PRD，架构师想的是概要设计，开发想的是接口规范，测试想的是测试用例库，客户想的是验收标准。这些文档的信息密度、更新频率、受众、生命周期完全不同，你却想用一个统一的标准去衡量「够不够」，这从一开始就不可能。

根据我这14年的实践观察，瀑布开发里的文档按目的可以分成四大类。我先把这个分类讲清楚，后面的所有讨论才有锚点。

1. 命令型文档

定义：写给机器或自动化流程执行的精确规范，不允许有歧义。典型代表包括API接口协议文档、数据库表结构定义、通信报文格式规范、自动化测试用例。这类文档的特点是：如果出现二义性，系统会直接报错或者产生生产事故。

2016年我在一个支付网关项目里亲眼见过一次事故：接口文档里对金额字段的定义是「Number类型，精确到分」，但没写清楚是整数分还是带小数点的元。对接方按照「元」传了12.50，我们这边按「分」解析为12分。这个歧义直接导致了一笔1250元的退款差额，法务介入之后追溯到的源头，就是接口文档里少写了一句不超过20个字的话。

命令型文档的「够」的标准非常明确：能被机器或自动化校验100%验证，不存在任何需要人口头补充的灰色空间。如果你能让CI/CD流水线自动检查接口协议的一致性、让自动生成的测试用例覆盖所有边界条件，那这份命令型文档就写够了。否则，一页都不算够。

2. 契约型文档

定义：用于划定组织间或角色间的权责边界，在出现争议时作为追溯和仲裁的依据。典型代表包括签字版的需求规格说明书、验收测试标准、非功能性需求承诺书、合规性声明。

契约型文档和命令型文档有一个本质区别：命令型文档追求的是准确性，契约型文档追求的是不可抵赖性。我服务过的某个城商行项目里，需求规格说明书每一页的右下角都要有甲乙双方的项目经理手写签名，整份文档385页，签到手软。我问过甲方的PM为什么不能电子签章，他的回答让我瞬间理解了这种文档的真实功能：「电子签太容易，他们就不认真看了。」

你看，这种文档的存在理由和内容质量几乎没有关系，它存在，是因为签字成本本身就是一种约束机制。所以判断契约型文档够不够，标准不是内容充分不充分，而是：当争议发生时，这份文档能不能让仲裁方快速判断责任归属。我在后面的章节会详细讲如何用最精简的内容达成这个目的。

3. 指南型文档

定义：帮助新人或接手者快速建立对系统的整体认知，降低上手成本。典型代表包括系统架构概览、部署手册、模块职责说明、关键决策记录。

指南型文档是四类文档里最容易被「过度编写」的。我刚入行的时候，被要求写一份模块设计文档，带我的老工程师说：「写到能让一个刚入职的毕业生看懂就行了。」我写了80页，用了大量的UML图、序列图、状态机图。交上去第二天被打回来了，批注只有一句话：「你写的不是指南，是自传。」

后来我才明白，指南型文档的「够」的标准不是全面，而是路径清晰。接手者不需要知道每一个细节，他需要知道的是：这个系统由哪些部分组成、各部分怎么交互、关键的坑在哪里、出了问题第一步看哪里。我现在的习惯是，指南型文档的前三页一定是系统交互全景图和关键风险清单，剩下的内容交给代码注释和wiki维护。

4. 故事型文档

定义：记录决策过程、背景推演、历史上下文，防止组织记忆丢失。典型代表包括架构决策记录、需求变更的原因说明、评审会议纪要里的关键争议点、上线后的复盘报告。

我在PingCode的客户现场见过一个特别典型的案例。某大型制造企业的IT团队在2018年做了一个ERP扩展模块，三年后原班人马走了一半，新来的技术负责人看着代码百思不得其解：为什么库存扣减逻辑不是放在订单服务里，而是放在一个独立的「库存预留」模块里？翻遍了所有设计文档都没找到原因。最后是离职的老架构师在微信里回复了一句话：「当年财务总监坚持要求库存操作必须有痕迹审计，独立模块才能保证每次扣减都生成审计日志。」这个信息在原始的需求文档里其实提过，但分散在财务需求章节的第4.2.3条和审计需求章节的第7.1.1条，没有人把它们串联成一条决策链。

故事型文档存在的价值，就是防止这种「决策上下文丢失」。它的「够」的标准很简单：当团队里所有人失忆，一个外部审计员读完你的故事型文档，能不能复现当时为什么会做这个决策。

好，现在我把这四类文档的定位和判断标准整理成一个表格，你可以随时回头对照：

这个分类框架是我在实践中反复打磨出来的。你在看后面的内容之前，脑子里先装上这四类文档的定义，不然很多判断逻辑你会觉得无法落地。

四、关于瀑布文档的四个致命误区

在给出判断方法之前，我必须先把几个最常见的认知误区炸掉。这些误区我已经在无数个项目评审会上见过，几乎每一个都会导致文档工作量翻倍，但交付质量原地踏步。

1. 「写得越多越专业」的幻觉

这个误区的根源是中国软件行业早期大量承接欧美日的外包项目，外方要求文档详尽到什么程度？我2009年参与过一个对日外包项目，日方发过来的模板里，一个登录功能的需求描述长达47页，包含12种输入组合的截图标注、每个文本框的像素级坐标、9种异常场景的完整交互流程。我当时觉得这就是「专业」的标准。

后来我去了甲方，自己开始带团队做从0到1的产品，才意识到那种文档的本质是跨时区、跨语言、对外包团队不信任环境下的过度补偿。47页的登录需求不是因为登录真的需要47页才能说清楚，而是因为甲方不敢信任乙方会主动考虑那9种异常场景。

在同一个办公室、同一种语言的团队里，你不需要把文档写到能外包给另一个时区的水平。我在PingCode服务过的很多产研团队，从100人到500人规模不等，一个明显的规律是：文档详实程度和团队信任度成反比。信任度高的团队，PRD可能就是20页的飞书文档加一个原型链接；信任度低的组织，哪怕开发坐在产品经理隔壁，也要走一套完整的SRS评审流程。

所以下次你觉得文档不够专业的时候，先问自己一个问题：我是在补内容的缺口，还是在补信任的缺口？如果是后者，写再多文档也只是在冰山上面盖被子。

2. 「将来有人接手所以现在必须写全」的过度远虑

这个观点听起来特别正确，但我见过太多反例。2018年我在一个电商平台做架构升级，前任留下的文档足足有800多页，按模块分门别类整理得井井有条。我们团队花了三周时间去读这些文档，然后发现了一个尴尬的事实：至少60%的文档内容已经和当前代码实现不一致了。代码在两年时间里经历了多次重构，但文档没有跟着更新，没人敢删，也没人敢改，因为「万一哪里还有用呢」。

这里有一个我总结出来的数据观察：一份超过6个月没有更新的项目文档，其可靠度会下降到50%以下；超过18个月没有更新，可靠度可能不到20%。这个数据来自我在5个项目里做的文档审计，每次审计都会抽样对比文档描述和当前代码实现的差异率。

所以「为将来的人写全」这个思路，在实际操作中往往适得其反，你留下的不是一份资产，而是一颗地雷。将来的人会以为文档是对的，照着理解，结果被坑。我现在的做法是：每个模块只保留一份不超过5页的指南型文档和一份决策记录，剩下的信息交给代码注释和测试用例。代码注释会随着代码一起重构，测试用例能自动验证行为，它们的可靠度远高于静态文档。

3. 「评审通过了就代表够了」的流程幻觉

我在某军工单位见过这样的场景：一份需求规格说明书经过了需求评审、设计评审、测试评审三轮审查，每轮评审都有签到表、会议纪要、问题跟踪表，流程完美无瑕。结果项目上线前一周，测试发现一个致命缺陷：需求文档里描述的数据加密算法和实际调用的算法不一致。翻回需求文档，那段描述确实在评审时没人提出异议，因为评审会上没人真正逐行验证那段技术描述的准确性，所有人都在关注业务流程、界面交互、权限控制这些自己熟悉的领域。

评审通过只代表流程合规，不代表内容正确。流程合规和内容正确之间隔着一个太平洋。尤其是契约型文档，评审会上最容易出现的情况就是：大家都默认别人已经仔细看过自己负责的那部分，谁也没发现整体逻辑上的断裂。

我的补救方法是：每条关键需求必须有一条对应的自动化验收测试用例。评审会上的口头发言我不信，我只信CI流水线里跑绿的那行结果。这个习惯帮我提前抓住了至少3次可能酿成大错的文档错误。

4. 「写文档影响开发效率」的二元对立

很多工程师讨厌写文档，觉得是浪费时间，觉得真正牛逼的程序员应该直接看代码。我在职业生涯的前五年也是这么想的，直到我自己接手了一个没有文档的遗留系统。那个系统里有一个800行的函数，没有任何注释，没有任何设计文档，我花了整整两周读那段代码，最后发现它实现的功能可以概括为三句话：接收订单、扣减库存、生成发货单。

这时候我突然理解了：不写文档省下来的时间，会在未来的某一天，由另一个人连本带利地还回去。那两周不就是我替三年前那个「效率至上」的前任还的债吗？

但反过来，我也不同意「所有东西都必须文档化」的另一个极端。好的文档不是写作，是用最低的维护成本传递最关键的信息。什么叫最低维护成本？就是你写的东西，未来改代码的时候顺手改它，改动量不超过改代码工作量的5%。什么叫最关键信息？就是如果这个东西丢了，接手的人无法在合理时间内靠读代码重新推导出来。

按照这两个标准，大部分细节实现其实不需要文档化，而架构决策、系统边界、异常处理策略这些东西，必须有轻量级的文档承载。

五、我的「四步判断法」：到底要写多少才能停笔

以上四个误区讲完，接下来是我这套方法论的核心，四步判断法。这个方法不是一次拍脑袋想出来的，而是在带过十几个项目之后慢慢沉淀下来的习惯。我不敢说它适合所有行业所有团队，但至少在产研协作密集的商业软件开发领域，它帮我多次在文档工作量上做到了「刚刚好」。

1. 第一步：先定义这个文档要解决什么「角色」的问题

动笔之前，先问自己：这份文档的目标读者是谁？他拿到这份文档之后要做什么决策或执行什么任务？

如果答案是「给开发人员看，他们需要知道如何实现这个功能」，那你写的就是命令型文档，需要精确到方法签名、参数校验规则、异常处理策略的程度，但不能写成教科书，不需要解释什么叫「乐观锁」，只需要描述本模块在什么场景下使用乐观锁。

如果答案是「给三个月后接手维护的人看，他需要快速理解系统结构」，那你写的是指南型文档，重点是宏观地图和关键风险标记，不需要深入到代码片段级别。

如果答案是「给法务和项目总监看，出了事好追责」，那你写的是契约型文档，重点是边界条件的明确定义和双方确认的验收标准，不需要把实现细节放进去。

如果答案是「给未来的自己或继任者看，为什么当年选了A方案而不是B方案」，那你写的是故事型文档，重点是当时面临的约束条件、候选方案的优劣对比、最终决策的依据。

这个第一步看起来简单，实际操作中却常常被跳过。很多文档写跑偏，是因为写的人没想清楚自己在写给谁看。他想的是「老板让我写一份设计文档」，于是把所有知道的东西都往上堆，最后写出了一个大杂烩。

2. 第二步：评估信息复杂度，有多少东西是「不说就不会知道」的

定义完读者和目的之后，进入具体内容的评估。我用的不是一个万字清单，而是一个相当残酷的过滤机制：

如果这个信息点，下游角色可以通过某种方式（看代码、看测试用例、看数据库schema、看API文档）自己推导出来，而且推导成本在可接受范围内，那它就不值得专门写进文档。

这个过滤条件能帮你砍掉大量冗余内容。举个例子：

• 系统的每个数据表有哪些字段？，不需要写在设计文档里，看DDL或者数据库注释就行。
• 为什么订单表拆成了三张子表而不是一张大宽表？，这个必须写进设计决策记录，因为看表结构的人无法反推出你当年的权衡过程。
• 某个接口支持哪些HTTP方法？，不需要写，看接口定义或者swagger文档就行。
• 为什么这个接口用POST而不是PUT？，必须写，因为RESTful规范建议PUT用于更新，你违反了规范一定有原因。

我用这个标准评审过很多团队的文档，效果非常明显，至少40%的文档内容属于「不说也能知道」的类型，砍掉它们不会影响任何人的工作，反而让真正重要的信息更容易被发现。

3. 第三步：评估变更频率，写得越细维护成本越高

这个维度的核心逻辑来自我在实际维护中的惨痛经验：文档写得越细，未来任何一次代码变更都需要同步更新文档，维护成本累积起来可能超过文档带来的收益。

我现在的做法是：

• 高频变更的信息，绝对不写进静态文档。比如具体的方法实现步骤、前端组件的布局细节、数据库索引策略的微调，这些东西进代码注释或者在持续集成报告里体现，比写进文档合理得多。
• 低频变更的内容，才值得花时间写清楚。比如系统对外接口的协议定义、核心数据模型、模块间的职责边界，这些东西一旦确定，半年一年都不会变，写一份高质量文档的ROI很高。
• 中频变更的信息，采用「骨架+链接」的策略。文档里只写骨架结构，细节指向代码仓库的具体路径。比如设计文档里写「订单模块的详细实现逻辑参见order-service/src/main/java/…」，未来代码变了，维护者只需要确认逻辑描述是否有结构性变化，不需要逐行同步。

这里有一个我固定使用的决策矩阵，你可以直接拿去套：

4. 第四步：引入「信任系数」调节最终产出量

这是我这个判断框架里最不常见、但我认为最关键的概念。

信任系数是指：文档的下游消费者对你的输出质量有多高的基线信任度。同一个团队合作三年以上的产品经理和开发，信任系数可能是90%。刚组建的外包团队和甲方之间，信任系数可能不到20%。

信任系数直接影响你需要写的文档量：

• 信任系数在80%以上：命令型文档写核心接口和边界条件就够了，故事型文档可以口头传递，契约型文档简化到只有验收标准。
• 信任系数在50%-80%之间：命令型文档需要覆盖主要业务流程和异常路径，契约型文档需要明确关键交付标准，故事型文档可以在Wiki上轻量维护。
• 信任系数在50%以下：四类文档都需要相对完整的产出，契约型文档需要走正式评审和签字流程，命令型文档需要包含完整的边界条件和异常处理描述。
• 信任系数低于20%：这是外包合作或者跨组织协作的典型场景。你需要命令型文档细到几乎可以自动化生成代码的程度，契约型文档需要法务参与，故事型文档也要整理归档留作证据。

注意，信任系数不是一成不变的。一个团队在合作初期信任系数可能只有30%，经过两三个迭代的磨合，信任系数会快速上升到70%以上。因此，文档策略也应该随之调整。初始阶段用较高的文档投入来建立信任，信任建立之后逐步精简到合理水平，而不是永远维持同一个文档标准。

我在PingCode服务过的一家智能制造公司，研发团队从20人扩张到了120人，经历了典型的信任系数变化过程。初创阶段几个核心成员之间沟通成本极低，文档极简；但规模上到50人以上后，新人涌入带来信任系数下降，他们花了大概半年时间重新建立了一套适配新规模的文档规范，不是简单地加量，而是用我上面这套框架重新评估了每类文档的受众、信息复杂度和变更频率，最终文档总量比100人时反而减少了30%，但交付质量反而提升了。

六、用PingCode的客户案例来验证这套推理

理论框架讲完了，接下来我用一个具体的观察案例让这套逻辑落地。由于职业原因，我接触过大量使用PingCode做研发管理的中大型团队，其中不少团队经历了从「小团队文档极简」到「规模扩大后文档失控」再到「重新建立文档规范」的完整过程。

我印象很深的是一个SaaS产品团队，研发人员规模在180人左右，分为12个特性小组。他们在扩张初期遇到了典型的文档问题：每个组的文档标准不一致，有的组PRD详细到200页，有的组只有几张截图加几句描述。跨组协作时，下游组件依赖方的工程师抱怨根本看不懂上游的设计文档，联调时大量时间花在口头对齐上。

他们当时的CTO找到我，问我有什么现成的模板可以统一标准。我给他的建议是：不要先上模板，先诊断每份文档的「读者-任务」匹配度。

我们一起做了两周的诊断，发现了一个非常集中的规律：

• 那些被抱怨「看不懂」的文档，几乎全部是写的人没有区分文档类型的案例。一份文档里混着命令型的接口定义、指南型的流程介绍和故事型的决策背景，读者找不到自己需要的信息层。
• 那些「太厚太多」的文档，大量内容是变更频率极高但价值密度很低的UI交互说明，程序员根本不看那部分，他们只看接口和数据结构。
• 那些「太简陋」的文档，缺少的是异常路径和边界条件的描述，而这恰恰是命令型文档最核心的内容。

最终他们做的事情不是大一统地强推模板，而是用我前文讲的四类文档框架，要求每份文档在首页标注自己的文档类型和目标读者，然后按照每类文档的「够了」标准来组织内容。半年后CTO给我反馈了两组数据：

• 文档平均长度从127页降到了43页，减少了66%。
• 跨组联调中「因文档不清导致的口头沟通时间」从每个功能平均3.2小时降到了0.8小时。

这个案例说明了一件事：瀑布文档不是输在量上，是输在结构上。一个知道自己在写给谁、写什么类型内容的团队，用40页能达到的效果，比一个无差别码字的团队用200页好得多。

七、不同行业场景下的文档策略取舍

前面讲的都是通用的判断框架，但实际落地时必须根据行业特性做调整。我在不同领域踩过不同的坑，分享一下几个典型场景的取舍原则。

1. 金融、医疗、航空等强监管行业

这类行业的文档策略有一个不可谈判的底线：合规性文档必须按照监管要求写全，没有讨价还价的空间。ISO 13485、DO-178C、PCI DSS这些标准里明确要求了哪些文档必须有、内容框架是什么、审批流程怎么走。

但这不意味着你只能无脑堆文档。我的经验是：

• 把合规要求的文档和其他文档严格分开管理。合规文档走合规流程，不要让它影响日常开发文档的节奏。两者的读者、目的、更新频率完全不同，混在一起只会互相拖累。
• 在合规框架内仍然可以应用变更频率和信任系数来判断详略。同样是SRS，医疗设备软件可能每一个需求都要追溯到风险分析文档，但电商支付系统的SRS可能只需要在资金流转相关的部分做详细追溯。
• 我在银行项目里用过的一个技巧：用可追溯性矩阵来「偷懒」。监管要求每个需求都要追溯到设计、实现和测试，但追溯方式可以是轻量级的。你不用把实现细节全部写进SRS，只需要在SRS里给每条需求分配唯一ID，在代码里用注释标注对应的需求ID，在测试用例里标注覆盖的需求ID，然后用工具自动生成追溯报告。这样文档总量不需要翻倍，但合规性完全满足。

2. 企业级定制开发、外包项目

这类场景的特点是信任系数天然偏低，而且是甲乙双方关系，出了问题要靠文档追责。在这种场景下，文档策略的核心是保护双方的利益边界，而不是追求信息传递效率。

我的建议是：

• 契约型文档是重中之重，必须写得滴水不漏。需求规格说明书的每一条功能描述都要对应一条验收标准，验收标准要具体到可以用自动化测试脚本验证的程度。
• 命令型文档的质量决定了交付物是否会被拒收。接口协议、数据结构、非功能性指标这些都要白纸黑字写清楚，并且和验收标准绑定。如果甲方中途改需求，这些文档就是变更费用的依据。
• 指南型文档和故事型文档可以适当简化。甲方不关心你的内部实现有多优雅，他只关心交付的东西是否符合合同。所以内部设计讨论的决策记录不用给甲方看，保留在团队内部Wiki里即可。
• 一页签字页比一百页技术描述更有法律效力。我在外包项目中养成了一个习惯：关键的功能边界、性能指标、验收条件都单独列在一两页纸上，双方签字盖章。这一两页纸在法律上的分量，远重于后面几百页的详细描述。

3. SaaS产品、互联网自有产品

这类场景的文档环境是最宽松的，因为团队通常是一个公司的同事，信任系数相对较高，而且没有甲乙方关系。但这反而容易走向另一个极端，完全不写文档。

我在互联网公司见过太多这样的产品团队：PRD写在飞书文档里，设计稿放在Figma，接口文档用Swagger自动生成，然后管这叫「文档齐全」。但当一个新同事入职，没人告诉他该看什么、顺序是什么、哪些信息是过期的，他会陷入信息沼泽。

我的建议是：

• 至少要有一份「系统全景图」级别的指南型文档。不用长，10-20页足够，包含系统架构图、核心模块职责、关键数据流、技术栈说明和常见问题索引。这份文档的更新频率可以很低（一个季度一次），但对新人的价值巨大。
• 架构决策记录是ROI最高的故事型文档。每次重大技术决策花半小时写一页纸的ADR，记录背景、候选方案、决策依据、预期后果。几乎零成本，但未来某天可能需要它救命。
• 命令型文档尽量自动化生成。API文档用Swagger/OAS，数据库文档用Schema注释工具，部署架构用基础设施即代码的配置文件。人写的文档总会过时，自动生成的总能保持最新。

八、也许你根本不需要「写更多文档」，你需要换个思路

写到这一节，我想抛出一个可能挑战很多人认知的观点：在2025年这个时间节点，很多传统瀑布文档应该被自动化验证手段替换掉，而不是继续堆人力去维护。

我举几个例子：

需求规格说明书里的业务规则验证，可以被自动化验收测试替代。你花三天写了一段描述订单拆单规则的文字，不如花一天写一组Gherkin格式的验收测试用例。后者不仅能被非技术人员读懂，还能直接挂在CI流水线里自动跑。需求变了，测试用例跟着改，文档永远不会过期。

接口协议文档的准确性校验，可以被契约测试替代。服务A和服务B之间的调用协议，你写了一份20页的接口文档，但联调时发现两边理解不一致。如果你用Pact这类契约测试工具，服务A生成一份契约文件，服务B的构建流水线自动拉取这份契约文件验证兼容性，不需要任何人手工对比文档和代码。

部署手册可以被IaC和容器化替代。一个应用怎么部署、依赖哪些中间件、配置文件长什么样，这些东西如果写在文档里，一定会过期。但如果写在Terraform或Kubernetes的YAML文件里，它天然就是可执行的、可版本管理的、自动更新的文档。

我在PingCode服务过的一家金融科技公司，把传统SRS里大约70%的业务规则描述转化成了可执行的验收测试用例，文档部分只保留业务流程概述和关键决策记录。结果他们的需求变更响应速度提升了40%，因为测试用例可以直接驱动开发，而不依赖开发人员去逐段阅读文档。

不是说文档不重要，而是说如果你的工作成果可以被自动化验证，那么最好的文档形式就是那个自动化验证本身。它永远不会和实际行为不一致，因为实际行为就是按照它来执行的。

九、一个可落地的「文档停笔检查清单」

前面所有的理论和方法论讲完了，最后我给你一份可以直接拿来用的检查清单。在提交任何一份瀑布文档之前，逐条过一遍，能通过就说明你写够了。不能通过的地方，就是你还需要补充的方向。

1. 通用检查项，适用于所有类型的文档

1. 我是否在文档开头明确标注了目标读者和他们的使用场景？，如果回答「没有」，马上去加。读者不知道这份文档是给他看的，他就不会认真看。
2. 我是否能回答「哪些信息是读者无论如何也推导不出来的」？，推导不出来的必须写，能推导的可以考虑删。
3. 文档里超过6个月都不会变动的信息有多少？低于6个月就变的信息有多少？，高频变的内容是否可以用链接或自动化方式替代？
4. 如果今天让下游读者拿着这份文档干活，他会不会还需要找我口头确认某些部分？，如果需要，说明那些部分没写够。
5. 我写的每一段内容，能不能经受住「有人在争议中引用这一段作为依据」的考验？，尤其是契约型文档，模糊的措辞等于白写。

2. 命令型文档专项检查

1. 输入输出的边界条件是否全部覆盖？，空值、超长值、特殊字符、并发冲突、超时重试这些场景的描述是否完整。
2. 错误码与异常信息是否明确定义？，下游调用方能不能根据错误码独立判断问题归属？
3. 是否有一个自动化流程可以验证这份文档的准确性？，如果没有，考虑是否需要建一个。

3. 契约型文档专项检查

1. 每一条承诺性质的描述，是否都对应了可客观验证的验收标准？，「系统响应速度快」不是验收标准，「95%的查询请求在200ms内返回」才是。
2. 边界外的部分是否明确标注了「不在本次交付范围」？，没有排除就等于默认包含，这是合同纠纷的常见源头。
3. 签字页上的内容，签字双方是否都真正读过并理解？，不要高估签字页的实际约束力，关键在于签字前是否建立了共识。

4. 指南型文档专项检查

1. 一个完全不熟悉系统的人，读完后能不能在30分钟内画出系统架构概图？，能，说明文档结构合理。不能，说明信息组织方式有问题。
2. 文档里是否包含过期的信息？，如果有，马上删除或标注「已废弃」。过期信息比没信息危害更大。
3. 文档的更新频率是否控制在合理范围？，指南型文档不需要随每次迭代更新，但至少每半年要review一次。

5. 故事型文档专项检查

1. 是否记录了当时面临的所有候选方案？，只写最终选择不够，未来的读者需要知道你还考虑过什么、为什么放弃。
2. 是否记录了决策时不可能知道的风险？，这是给未来接手者的预警，告诉他哪些地方可能会有坑。
3. 文档长度是否超过2页？，故事型文档超过2页通常意味着混入了指南型或命令型的内容，考虑拆开。

这个清单不长，但每一条都是我用实际项目的教训换来的。你在用的时候不用全部做到完美，但至少在你觉得「这份文档应该差不多了」的时候，用这个清单再审视一遍，通常能帮你揪出2-3个遗漏点。

十、写在最后：文档的尽头不是完美，是「刚好够用」

用了将近一万字来讨论「多少才算够」，其实我想说的只有一句话：

瀑布开发里的文档，从来就不应该追求写全、写透、写到无懈可击，它应该追求写到刚好够下游干活、刚好够应对审计、刚好够保护自己、刚好够被未来的接手者理解。

「刚好」这两个字，难就难在它不是绝对值，而是随着项目类型、团队规模、信任关系、监管环境动态变化的一个区间。你用页数、字数、章节数去丈量它，就像用体温计去测血压，工具和对象根本对不上。

所以我把这个话题最后的落点，放在「判断力」而不是「标准答案」上。你不需要记住SRS应该写多少页、设计文档应该包含几个章节、接口规范要写到什么颗粒度。你只需要在你下一次动笔之前，停下来想三个问题：

1. 这份文档写给谁？他要用它干什么？
2. 里面的信息，有多少是不说就不会知道的？有多少是半年内一定会变的？
3. 这份文档如果明年才被人看到，它还值得被信任吗？

想清楚这三个问题，你的答案自然会出现。想不清楚，写再多也只是在硬盘里占地方。

如果你想进一步搭建自己团队的文档规范，我建议你下一步做的事情是：把你们团队最近三个月的核心文档拿出来，用我第三节的四类文档框架重新分类，再用第十节的检查清单逐条排查。在不增加任何人工作量的前提下，你大概率能找到至少30%的冗余内容，把这些时间省下来，用在真正有价值的文档上。

文档够了，人就轻松了。人轻松了，才有力气把代码写好。