你的文档在欺骗用户
Source: Dev.to
让我们直截了当：你的文档现在很可能在对用户撒谎。不是恶意的，也不是有意的，但仍然是谎言。
那三个月前就已废弃的接口？仍然被记录为可用。
在 v2.3 中改名的配置标志？仍然显示旧名称。
那个因为产品演进而需要 47 步的“快速入门”指南？
每天，开发者都会打开你的文档，按照已经失效的指令操作，随后悄悄得出你的产品有问题的结论。他们不提交 bug，也不抱怨，只是离开。
计算不成立
文档的衰减速度快于你维护的速度。
每一次功能发布、每一次 API 变更、每一次 UI 更新、每一次变量重命名，都可能导致文档漂移。 在一个每周都有发布的健康工程组织中？这意味着每个产品每年有 50 多个潜在的文档地雷。
现在看看你的文档团队。一个人？两个人？更愿意写代码的兼职贡献者？这套算式根本行不通。
“We’ll Update Docs Before Release”
每个团队都会这么说。几乎没有团队能持续做到。
为什么？因为文档更新要与功能发布竞争。而功能发布总是赢——每一次。
你的 CI 在合并前捕获代码错误。你的测试捕获回归。你的 linters 捕获风格违规。
什么能捕获文档漂移？三个月后的客户投诉？某位因过时指引浪费了一小时的支持工单？那不是系统，那是希望。
将过时文档视为 bug——而不是“可有可无”或“我们以后再处理”。
当文档的描述与产品实际行为不一致时，这就是客户体验中的缺陷——可靠性问题。Bug 会被记录、排序并修复。而文档漂移只会不断累积，直到有人注意到，通常是抱怨的客户。
实际有效的做法
1. 自动化检测，而不仅是编写
难点不在于写文档，而在于知道何时需要更新文档。当你的产品发生变化时，应该有机制标记哪些文档可能已经不准确。示例警报：
“此 PR 修改了认证流程。这 4 页文档引用了认证。”
2. 将文档放入与代码相同的工作流
Docs‑as‑code 同时是一种存储方式和工作流策略。如果文档与代码存放在同一个仓库、在同一 PR 中审查、在同一 CI 中测试，它们会得到与代码同等的关注——不是因为人们突然更在意，而是系统对待它们是平等的。
3. 让 “完成” 包含文档
功能在文档更新之前不会发布。破坏性变更在迁移指南完成之前不会合并。这不是建议，而是一个门槛。
工具链缺口
对于代码质量，我们有 linters、formatters、类型检查器、测试框架、安全扫描器、依赖审计工具。
对于文档质量，大多数团队依赖有时间时人工阅读。这种差距导致文档腐烂速度比代码更快。
解决方案不是增加人力，而是将我们已经用于代码的同样自动化检查应用于文档：持续验证、系统化强制执行。
- 风格指南违规 → 自动标记。
- 链接失效 → 在 CI 中捕获。
- 术语不一致 → 像代码风格一样强制执行。
实际成本
“我们的文档有点过时”听起来微不足道，但隐藏的成本却是真实存在的：
- Support tickets 因文档导致的问题而产生的工单
- Lost deals 当潜在客户无法完成快速入门时失去的交易
- Churn 因用户认为你的产品不可用而产生的流失
- Engineering time 用于回答本应由文档解决的问题的工程时间
- Reputation damage 在每个 “your docs are wrong” 的 GitHub issue 中造成的声誉损害
大多数团队从未将这些成本与文档关联起来；它们分散且延迟出现，却会累积。
挑战
花 10 分钟完成以下操作：
- 选择你最重要的用户旅程（signup、首次 API 调用、基本 integration）。
- 像从未见过产品一样，按照自己的文档进行操作。
- 记录所有指令与实际不符的地方。
大多数团队在最关键的流程中会发现 3‑5 个问题——这些是用户每天都会遇到的问题。这不是文档的问题，而是隐藏在显而易见之处的客户体验漏洞。
我使用的工具
完全披露：我使用 EkLine 进行自动化文档审查。它在 CI 中运行，标记样式问题，捕获失效链接，并在产品变更影响文档时提醒我。
它并不是唯一的选择。如果你想构建自己的系统，Vale 非常出色。关键不在于工具——而在于以我们对代码所用的同样严谨来对待文档。
无论你使用什么，第一步都是相同的：不要把文档视为写作问题。要把它视为系统问题。写作从来不是难点。
你文档中最古老的谎言是什么？我真的很好奇——请留下评论。没有评判。我们都经历过。