工程文档怎么写：让后来的人能接得住系统
摘要
工程文档不是把代码重新描述一遍，而是帮助后来的人理解系统为什么这样设计、如何运行、如何修改、出问题时怎么恢复。好的工程文档记录上下文、边界、流程、关键决策和常见故障，让系统不只依赖某个人的记忆。
文档是系统的一部分
很多团队把文档当成额外负担。
代码写完以后，有空再补；没人催就不写；出了问题再临时整理。
但工程文档其实是系统可维护性的一部分。
没有文档，后来的人只能通过代码、聊天记录和猜测理解系统。理解成本越高，修改风险越大。
文档不是为了好看，而是为了让系统能被接手。
先写给谁看
写工程文档前，先确认读者。
是新加入的工程师，还是排查问题的维护者？是产品同学，还是未来的自己？不同读者需要的信息不同。
新同学需要整体结构和启动方式；维护者需要故障处理和日志位置；协作者需要接口边界和依赖关系。
文档写给所有人，最后可能谁都不够用。
明确读者，文档才会有重点。
记录系统边界
工程文档最应该写清楚边界。
这个模块负责什么，不负责什么？输入从哪里来，输出到哪里去？依赖哪些外部服务？哪些事情是人工处理，哪些是自动处理？
边界清楚，后来的人才知道修改影响范围。
如果边界不清，任何小改动都可能变成全局冒险。
系统不是只由代码组成，也由边界组成。
记录关键决策
代码能告诉你现在怎么做，但不一定告诉你为什么这样做。
工程文档应该记录关键决策：
- 为什么选这个方案？
- 当时有哪些约束？
- 放弃了哪些替代方案？
- 哪些条件变化后需要重新评估？
这些信息非常宝贵。
没有它，后来的人可能会重复讨论，甚至误删看似奇怪但有历史原因的设计。
写清运行和恢复流程
工程文档必须包含可操作内容。
比如如何本地启动，如何运行测试，如何发布，如何查看日志，常见错误如何处理，如何回滚。
这些内容在平时看起来普通，出问题时非常重要。
尤其是恢复流程，要写得具体。
事故发生时，人会紧张。越具体的步骤，越能降低出错概率。
保持文档不过期
过期文档比没有文档更危险。
它会给人错误信心。
所以文档要和系统一起维护。改了流程，就更新文档；删除了接口，就同步说明；发现文档不准，就马上修。
不必追求文档覆盖所有细节，但关键路径必须可信。
一份小而准的文档，胜过一份大而旧的文档。
结论
工程文档怎么写？先明确读者，再写清系统边界、关键决策、运行流程、恢复方式和维护规则。
好的工程文档不是代码翻译，而是上下文保存。
它让后来的人能接得住系统，也让未来的自己少一点猜测。
没有评论:
发表评论