为什么需要文档工程
我们需要知道，文档工程不是为了制造文件，而是为了让知识具备结构、边界、演化路径与可追溯性。
大部分项目中的文档建设会走向两个极端：
- 几乎没有文档，知识全在代码、聊天记录与个别人脑子中；
- 建立了很多文档，但是只是静态文件堆积，没有明确的职责以及演进机制。
这种文档建立方式会大大增加新加入项目的成员的理解成本与上手难度，在当今使用AI辅助开发的情况下，这个问题被无限放大。所以，文档工程的建立，不只为了让人看懂项目的整体架构流程、调用关系，也为了让AI明白项目边界，明确开发目的并减少Bug发生率。也就是说，文档工程并不是要解决文档数量的问题，而要解决知识组织的问题。它回答的是这几个问题：
- 什么信息应该被记录；
- 这些信息应该被记录在哪里；
- 代码以及相关业务变化时，哪些文档应该跟着变化与调整。
所以，文档工程应该首先满足结构设计的要求，其次才是内容的填充。
文档工程的层次
规范层
该层主要回答的问题是：
- 文档应该怎么写
- 目录应该怎么分
- 哪些改动会触发文档的更新
- 模板以及约束放在哪里
规范层不是项目成品，也不是任务记录。它是对于所有文档以及项目的架构约束
过程层
该层主要回答的问题是：
- 这次任务做了什么
- 该改动影响了哪些模块
- 做过哪些验证
- 是否涉及数据库、接口、业务规则或者技术架构的变更
过程层不是给外部写作者长期阅读，而是给开发与执行提供后续的参考依据和溯源证据
成品层
该层回答的主要问题是：
- 系统现在对外暴露了什么
- 某个模块的接口、业务规则以及架构边界是什么
- 产品、测试、实施、研发应该读哪份正式文档
成品层需要稳定、清晰并且可阅读，需要让项目组中的人可以最快看懂。同时该层不应该混入任务排障记录、临时决策碎片以及草稿式备注。
为什么需要分为三层
我们需要把这三层分开撰写，这是因为这三层描述的是完全不同且相互独立的东西。当我们将这三层混在一起的时候，项目就不再具备可推理性。而所谓的可推理性是指：
- 看到一个改动，就能知道应该更新哪类文档
- 看到一个文档，就能知道它描述的是规则、过程或者成品
- 看到一个目录，就可以知道它在服务谁
而文档工程的价值正是建立在这种可推理性上。
评论