第2章文档编写核心原则

二、文档编写核心原则：清晰性、一致性、完整性、可追溯性、可维护性

说实话，我见过太多汽车软件项目，代码写得漂漂亮亮，文档却一塌糊涂。有一次，一个同事离职后，我接手他的项目。打开文档一看，嗯，该有的都有，但就是读不懂。为什么？因为文档没有遵循基本原则。

文档不是写给自己看的，是写给团队看的。我个人习惯把文档编写比作盖房子——地基打不好，后面全是坑。今天我就把这五个核心原则掰开揉碎了讲给你听。

清晰性，说白了就是让人一眼看懂。我在项目中遇到过一份需求文档，光看标题就猜不出内容。打开后，满篇都是「相关模块」「适当处理」这种模糊词。你想想看，这种文档谁敢用？

清晰性的三个关键点：

我的小技巧：写完一段后，找个不熟悉项目的人读一遍。如果他问的问题超过3个，说明清晰度不够，重写。

一致性这个问题，我踩过不少坑。曾经有个项目，A模块用「ECU」表示电子控制单元，B模块用「控制器」，C模块用「控制单元」。结果评审时大家吵了半天，才发现说的是同一个东西。

为什么会这样？因为没有统一的术语表。

避坑指南：我曾经因为术语不一致，导致测试用例写错了。测试人员以为「唤醒」和「激活」是两回事，结果多测了20个无效用例。记住：一致性不是小事，是效率的保障。

完整性，就是文档要自包含。我记得有一次评审架构文档，发现缺少异常处理部分。我问作者：「系统崩溃了怎么办？」他说：「哦，那个我忘了写。」——你看，这就是完整性的问题。

完整的文档应该包含：

我的检查清单：写完文档后，我会问自己三个问题：

如果有一个答案是「不能」，说明完整性不够。

可追溯性，说白了就是「为什么这么做」。我见过太多文档只写「做了什么」，不写「为什么这么做」。结果半年后，没人记得当初的决策依据。

举个例子：

// 不好的写法
// 使用CAN总线通信

// 好的写法
// 使用CAN总线通信，原因：
// 1. 满足实时性要求（延迟<10ms）
// 2. 成本低于以太网方案
// 3. 与现有平台兼容
// 决策日期：2024-03-15
// 决策人：张三

可追溯性需要做到：

我建议：在文档中建立一个「决策日志」表格，记录每个重要决策。这样即使过了两年，你也能知道当初为什么选A不选B。

可维护性，是这五个原则里最容易被忽视的。你想想看，一个项目动辄三五年，文档如果不好维护，最后就是一堆废纸。

我见过最夸张的案例：一个项目的架构文档有200多页，但没人敢改。为什么？因为文档结构太乱，改一处可能影响十处。最后大家干脆不维护了，文档成了摆设。

如何提高可维护性？

避坑指南：我曾经维护过一个文档，里面引用了10个外部文件。结果有3个文件路径变了，文档里的链接全失效。从那以后，我坚持「文档自包含」原则——能不放外部引用就不放，非要放的话，用相对路径并注明版本号。

这五个原则不是孤立的，它们互相影响。我画个简单的逻辑图给你看：

嗯，这里要注意：不要为了追求某个原则而牺牲其他原则。比如，为了完整性把文档写成百科全书，反而降低了清晰性。找到平衡点，才是高手。

总结一下：

这五个原则，我用了15年才真正理解。希望你从一开始就重视它们，少走弯路。

公众号:蓝海资料掘金营，微信deep3321