我见过太多团队把 AI 生成的技术文档直接挂到 Wiki 上结果新人看完还是不知道怎么跑起来。问题不在 AI。你给它的 prompt 再详细它默认的写作目标也是把信息说清楚而不是让特定读者能动手。技术文档真正的品控标准是把读者会卡在哪一步前置到写作过程里。一份文档好不好不看信息全不全看读者能不能独立跑通去年我们有个服务升级我把 AI 生成的迁移文档发给组里一个后端同学测试。他照着做了四十分钟最后跑过来问这个配置里的region到底填哪个我回头看文档发现 AI 确实写了配置项列表每个字段都有类型和说明。但region那栏只写了服务所在区域。对熟悉的人来说够用了对第一次接触的人来说就是天书。这就是技术文档最常见的 80 分陷阱信息完整但读者视角缺失。AI 特别擅长生产这种说明书式文档。它会列参数、会分步骤、会加代码块看起来专业读起来空洞。因为模型判断好文档的标准是结构完整而不是读者能不能零依赖复现。三个最隐蔽的读者视角错误第一个是假设读者知道你在省略什么。AI 写安装步骤时经常这样bash克隆仓库git clone xxx安装依赖npm install启动服务npm run dev 看起来没毛病。但如果你让一个新人执行他会在第二步卡住Node 版本不对、Python 编译环境缺失、私有仓库没配 token。AI 默认环境已经准备好了但真实读者的环境千奇百怪。好的技术文档要在第一步之前加一个前置条件小节把环境版本、必须安装的底层依赖、可能遇到的权限问题列清楚。这不是啰嗦是给读者省时间。第二个是把能运行和能看懂混为一谈。AI 生成的代码示例通常能跑但例子本身太干净反而说明不了问题。比如教别人用熔断器示例代码里只展示了正常返回值没有超时、没有降级、没有异常传播。读者看完后知道语法但不知道什么场景下该用。技术文档的示例必须带点毛边。你得展示错误输入长什么样展示异常时会发生什么展示配置参数调大调小分别有什么后果。读者真正需要的不是一份语法参考而是一份我遇到这个情况该怎么办的地图。第三个是术语前面不加读者过滤器。AI 写文档喜欢堆术语因为它觉得术语是专业性的体现。但术语对不懂的人来说就是噪音。比如一段话里同时出现幂等性最终一致性 saga 编排对老手是密度对新手是劝退。我的做法是每个术语首次出现必须带一句解释或者链到前置文章。这不是降低文档水准而是尊重读者的认知路径。给技术文档装一套品控规则我们后来在团队里给 AI 输出技术文档加了五条 MUST 规则每个代码示例必须标明运行环境版本每个配置项必须给出一个真实可填的值不能只有字段说明每个操作步骤之间必须有过渡句说明这一步解决什么问题每个术语首次出现必须附加一句话解释或链接文档末尾必须有一个常见问题小节至少包含三个真实可能踩的坑。这五条不是让文档变长而是把读者会怎么卡住变成可检查清单。SHOULD 层级的规则更偏体验尽量提供错误示例和正确示例的对比复杂流程配一张时序图或状态图涉及性能的地方给出基准数据。MAY 层级则是锦上添花延伸阅读、相关 RFC 链接、社区讨论。规则比 prompt 更稳有人可能会问我直接在 prompt 里写面向新手不就行了短期可以长期不行。prompt 是黑箱输入换一个人、换一个模型、多轮对话之后约束就会衰减。规则文件是显式契约可以版本管理、可以回归测试、可以交给 CI 检查。我们在 sharp-tech-writing 模块里把这几条规则固化下来配合黄金样本集做回归。每次模型升级或者换 prompt 模板先用样本集跑一遍看文档的读者通过率有没有掉。这套做法对其他 AI 输出也适用。技术文档只是最容易被忽视的一个场景——它看起来能读但离能用往往只差一层品控。我在做一个用卡皮巴拉讲设计模式的微信小程序「爪爪代码冒险记」23 个设计模式用漫画 答题的方式讲目前正在开发中。如果你觉得这类内容有意思搜一下「爪爪代码冒险记」或者等我后面的文章。