为什么文档即将再次变得重要
文档有个名声问题。它被视为开销——你写它是因为不得不写，而不是因为它创造价值。最优秀的工程师写代码，稍逊一筹的才写文档。这是大多数工程组织中普遍存在的态度，而这种态度即将变得代价高昂。
为什么文档以前会失败
文档之所以失败，是结构原因，而非文化原因。它写起来费力，难以保持更新，也难以搜索。ROI 之所以不明朗，是因为回报总是在未来——当有人需要理解几个月前做出的决定时。
结果，文档萎缩了。团队不再写文档。新成员从代码和询问同事中学习。知识变得部落化且脆弱。这之所以可行，是因为退路永远是“去问当时在场的人”。
AI 改变了什么
AI 从根本上改变了文档的经济学。
首先，AI 让文档变得有用。一份写得很好的架构决策记录，会成为 AI 可以阅读、索引并据此回答问题的东西。它成为组织智能的一等输入。文档不再是你某天可能会读的参考资料——而是你的 AI 系统每天都在使用的活知识源。
其次，AI 让文档易于产出。AI 可以从代码、从 pull request 讨论、从事故事件时间线中起草文档。人的工作从写文档转变为审查和验证文档——这更快也更准确。
新的文档飞轮
正在解决文档问题的组织发现了一个良性循环：
- AI 从代码和对话中生成文档草稿
- 人类审查并验证草稿，补充 AI 无法推断的背景
- AI 对经过验证的文档建立索引，并用它回答未来的问题
- 文档越多，AI 的回答就越好
- AI 的回答越好，人类花在反复回答同样问题上的时间就越少
这改变了激励机制。文档不再是为不确定的未来收益而付出的努力，而是今天付出、却能复利的努力——因为每一份经过验证的知识，都让未来的每一次 AI 交互更加准确。
什么让文档对 AI 有价值
并非所有文档对 AI 都同等有用。对 AI 消费而言最有价值的文档有三个特征：
- 结构化: 清晰的章节、一致的格式、带有理由的明确决策
- 情境化: 为什么做出这个决定，而不只是决定了什么
- 互联: 与相关决策、系统和事件的关联
对 AI 友好的文档，最佳格式是架构决策记录（Architecture Decision Record）。每条 ADR 记录一项决策、所考虑过的替代方案，以及理由。AI 系统可以摄取 ADR，并以自由形式文档无法支持的方式对它们进行推理。
实际起步
如果你想让组织的文档为 AI 做好准备，就从 ADR 开始。哪怕你只有几条，也要确保它们遵循一致的格式。然后让你的 AI 助手依据它们回答问题。AI 能回答的东西与人们所问的问题之间的差距，会精确告诉你接下来该在哪里写。
令人不安的真相
在 AI 时代，文档不是开销，而是基础设施。投资它的组织将拥有理解自身背景、历史与约束的 AI 系统；不投资的组织将拥有通用化的 AI 系统——而通用化的 AI 正日益与大宗商品无异。
如果你的 AI 助手能读到你的组织做过的每一个决定，它能回答多少问题而不必升级给人类？