文档是生产力问题（AI让它变得可见）
Source: Dev.to
长时间以来，我们把文档视为一种卫生问题
你 应该 做的事。后来才变得重要的事。并不会真正影响今天的生产力的事。
AI 让人们明显看到这种假设有多错误。
当 AI 让我们更快，却又不知为何更慢
六个月前，我们在开发工作流中引入了 AI。
一切立刻加速：
- 代码草稿在几秒钟内出现
- API 规范自动生成
- 重构建议随时可得
- 每个问题都有自信的答案
纸面上，生产力飞涨。
但实际操作中，出现了奇怪的现象。
我们花更多时间重新阅读文档，而不是撰写它们。
看似已定的决策在后续讨论中不断被提起。
团队成员犹豫不决：“等等，哪个版本才是正确的？”
我们并没有在产出上变慢。
我们在决策上变慢了。
这时我们终于明白：
文档并不是副任务。它一直是瓶颈。
AI 并没有制造问题，而是把它暴露出来。
改变一切的事件
三个月后，我们遇到了上下文大小溢出的问题。当 AI 试图重构核心模块时，无法将所有内容一次性加载到内存中。
于是我们开始删除旧文档。
随后我们意识到：我们无法判断哪些文档是安全可以删除的。
- 有些文档包含了解释我们为何选择方案 X 而非 Y的上下文。
- 有些文档只完成了一半，但没有人记得这是否是有意为之。
AI 一直在重写文档以“保持整洁”。我们之所以接受这些更改，是因为它们听起来更好。
但每一次重写都抹去了上下文。每一次简化都去除了我们已经忘记的约束条件。
我们虽然行动迅速，却失去了回顾的能力。
糟糕文档的真实代价
- 没有明确的真相来源 — 多份文档声称拥有权威
- 静默覆盖 — 过去的决定在没有痕迹的情况下消失
- 结论缺乏上下文 — “我们决定 X”却没有“因为 Y 不可能”
- 责任随时间模糊 — 谁决定的？谁可以更改？
在 AI 之前，这种损害是慢慢累积的。人们通过记忆、走廊聊天和组织知识来弥补。
AI 消除了这种缓冲。它把所有文档视为同等权威。它无法猜测哪个决定是临时的，或哪个约束已不再适用。
因此，隐藏的成本立即显现：
决策摩擦是最昂贵的低效形式。
速度不是生产力
大多数生产力工具都在优化输出速度。
AI 在这方面非常擅长。
但没有边界的速度会产生一种新的浪费：
- 自信的答案却忽视关键上下文
- 解决方案悄悄超出原始意图的范围
- 看似最终的决策却从未得到验证
- 看似完整的文档却在三个月后无法使用
真正的生产力并非产生更多产出物，而是：
- 减少返工 — 不要重复做同样的决定
- 让决策更安全 — 知道可以更改什么
- 降低认知负荷 — 信任你的文档
- 长期保留意图 — 理解 why，而不仅是 what
而文档正处于这一切的核心。
Source: …
我们的改变：将文档视为系统，而非文本
我们不再把文档当作“内容”，而是把它当作 基础设施。
这种基础设施能够：
- 保留上下文，而不仅仅是结论
- 追踪责任，而不仅仅是结果
- 明确不确定性，而不是隐藏它
- 拒绝静默更改——每一次编辑都可见
- 在需要判断时停止
我们进行的一些具体转变
- 每份文档现在都有生命周期 – 活跃 / 已废弃 / 已归档 – 永不删除，只会转换状态
- 过去的决策永不被覆盖 – 当决策改变时，我们将旧的标记为 已废弃 并撰写新的。历史保持可见。
- 假设被标记为假设 – 我们给声明加上
[Explicit]（明确）、[Inferred]（推断）或[Assumed]（假设）标签。 - AI 管理结构和历史 – 它可以重新组织、摘要、格式化——但不能做出决定。
这并不是在控制 AI。它是为了重建信任。
我们的 AI 最有成效的事情
有时，我们的 AI 什么也不做。
它会停下来并说：
- “此更改会影响当前范围之外的决策。需要人工审查。”
- “此文档与先前的约束冲突。哪一个优先？”
起初，这让人觉得有摩擦。我们希望 AI 能解决问题，而不是制造更多疑问。
但随着时间推移，其效果不容否认：
- 更少紧急撤销“已完成”的工作
- 更清晰的决策边界
- 整体进展更快
矛盾变得清晰：提前停止比事后修复更快。
为什么这并不适合所有人
如果你希望 AI 能够：
- 为你做决定
- 平滑不确定性
- 无论如何都持续前进
这种方式会让人感到不舒服。
它的前提是：
- 人类仍然负责判断
- 边界比速度更重要
- 生产力是累积的，而非立竿见影
它要求你接受，有时最快的路径是 放慢脚步并澄清。
但如果你曾经感觉 AI 让你的系统既更快又更脆弱——
如果你曾经因为没人记得决策的原因而不得不撤销一周的工作——
如果你曾经问 “哪个版本是正确的？” 却得到三个不同的答案——
那么你已经知道：
- 文档不是负担。
- 它是你的生产力引擎。
转变
AI 并没有打破文档，它最终让文档的重要性不可忽视。
多年来，我们可以靠人类填补空白而容忍凌乱的文档。
AI 揭示了每一个空白、每一个歧义、每一个沉默的假设。
它迫使我们问自己：文档真正起作用意味着什么？
答案… (原文中被截断)
R wasn't about better writing. It was about better infrastructure.
**Documentation isn't about describing what you did.**
**It's about preserving your ability to decide what to do next.**
That's the problem AI made visible.