为什么 AI 的技术文档这么难读以及解法
文章目录
我其实很不喜欢 Codex 写的技术文档。明明都是中文，读起来就是很费事。
本文可以解答你的疑问，并且可以帮你使用 hai-simplified-technical 解决这类问题。
我们先锐评一下 AI 写的文档， AI 有时会在文档里写
下次重启时，它会启动失败。
它是谁？
假设前文同时提到了服务和 config-agent。这句话里的“它”，指哪一个？你可能去查服务，也可能去查 config-agent。句子没有给出足够的信息。人脑会分配一部分精力去理解这些东西。
同一句话，读出两种意思，下一步就可能走向两个方向。AI 技术文档还有很多臭毛病，叠加在一起，读起来就很不通畅。
为什么？
一 · 句子没错，但能读出两种意思
技术文档里最常见的毛病，看起来语法基本也难说是错的。问题在于，每一种都给读者留了一个猜的位置。
“进行了优化”：优化了什么？加了索引，还是改了缓存？动作埋进了名词，读者只知道“做了点事”。
“在适当的时候清理”：什么时候算适当？作者心里有答案，但没有写下来。
“设置、参数、配置”：写的人知道这是同一个文件，读的人会以为是三样东西。
“最好尽快检查一下”：这是必须做，还是可以不做？
“重启（如果有改动）”：读者读到“重启”，可能已经动手了，括号里的条件还没读到。
单看哪一句，都是小事。但一份文档中有几十句这样的话，每一句都要读的人猜一次。
读者变了
同事读到含糊的地方，可能靠项目经验补上意思，也可能来问作者。但这些上下文未必写进了文档。
当 README、操作手册（runbook）、AGENTS.md 被交给 Coding Agent，文档里的省略就可能变成执行时的假设。它读到“设置”“参数”“配置”，并不总能知道作者是不是在说同一个文件。
含糊的代价变了： 含糊不仅让读者/Agent 困惑，还可能让执行者做错一步。
“写清楚一点”没法检查
我们都知道文档要写清楚。但只说“清楚”，还不够指导修改：到底哪个词有歧义，哪个条件漏了，哪句话该拆开？
只让 AI “写清楚一点”，也可能得到更多解释和修饰，原来的歧义却还在。
我需要的是一条条能检查的规则：这个词能不能用，这句话该不该拆，这条警告该放在哪。
信息密度太高
开发正在从「写出高度可读的代码」演变成「写出高度可读的文档」。但大部分 AI 都被训练成了讲黑话的模样，可能是为了省 token，明明一小段能条理清晰的说清楚，方便定位，但非得压缩成两三句话，让老手才能看半天懂，这并不好。
当然，上面的一些臭毛病不仅仅是 AI 有，人类写的文档也有
那怎么解呢？
二 · 解法：从飞机维修手册借规则
去找最怕读错的行业，谁最怕读者读错？是飞机维修。
维修手册的读者，是照着手册动手的人。读错一句，就做错一步。
ASD-STE100，简化技术英语（Simplified Technical English，下文简称 STE），起源于航空维修文档。它用受控的词汇和写作规则，帮助读者准确理解英文技术说明。它的前身 AECMA Simplified English Guide 于 1986 年发布。来源：ASD-STE100 官网。
把一份部署 runbook 放在维修手册旁边，会发现它们面对着相似的写作问题：读的人要照着动手；警告在步骤前面；一步只有一条指令；条件写在指令前面。
STE 是为英文写的，我做了中文的适配，中文版一共 46 条规则，分 9 章：词、名词短语、动词、句子、操作步骤、说明文字、警告、标点和长度、写作习惯。英文版 49 条，多出的 3 条只管英语语法。
中文规则分两种。28 条是硬规则，必须严格遵守；18 条是软规则，守到八成，不守的每一条都要写出理由。规则文件展开了这些要求，并提供理由、例子和检查方法。
规则用起来，像换零件：找到有问题的说法，拆下来，装上一个只有一种读法的说法。
“对日志进行压缩处理”，拆掉“进行”和“处理”，剩下“压缩日志”。“在适当的时候清理缓存”，需要换成已经确认的触发条件。“它负责重试”，需要换成确实负责重试的组件名。
上图是构造示例：假设我们已经确认“配置文件改动后要清缓存”，也已经确认 Pool 负责重试，才能这样改。如果原文和项目资料都没写清楚，技能应把问题列给作者，不能为了句子完整，替系统发明一个行为。
46 条规则可以交给 Agent 逐条参考，再用脚本和人工判断检查结果。把规则写下来，执行就有了共同的依据。
日常写作时，人未必需要随时记住 46 条编号，更有用的是记住它们背后的取舍。所以我把这些规则背后的审美压成了十句话，句式向《Python 之禅》致敬。
-
复杂胜于晦涩。条件、例外和风险一条不少，晦涩的措辞一个不留。
-
明确胜于隐含。写出谁在做；主语换了，就写出来。
-
名字胜于代词。“它”可能指两个东西时，写名字。
-
一个东西，一个名字。配置就叫配置，除非场景必要，不换着叫设置和参数。
-
动词胜于名词。写“压缩日志”，不写“对日志进行压缩处理”。
-
具体胜于笼统。写出数字、名称或条件；写不出，就删掉形容词。
-
扁平胜于嵌套。一个名词前，最多挂两个“的”。
-
先说做什么，再说为什么。条件在指令前，警告在步骤前。
-
面对缺口，拒绝编造。不编数字；缺的证据列给作者。
-
规矩胜于感觉，实用胜于纯粹。硬规则必须遵守；软规则遵守八成，不遵守写理由。
这十句话是便于记忆的概括，遇到具体问题仍以 hai-simplified-technical 规则全文为准。第八句尤其需要分场景理解：警告先给指令，再说明风险；操作的前提条件放在指令前；解释整组步骤的原因，可以放在步骤列表前。
我最想先讲第一句：复杂胜于晦涩。
很多人以为“简化”就是把句子删短。其实这套规则删的不是复杂，是晦涩。
条件、例外、风险、还不确定的地方，一条都不能少。为了句子短而删掉一条警告，那是破坏，不是简化。要删的是裹在内容外面的那一层：包装动词、空的程度词、指代不清的“它”。好的技术文档一定是减少阅读理解中「不必要的理解」，看完就能照着做，方便定位。
而内容本身可以复杂，因为实际情况就是很复杂，但措辞却丝毫不能晦涩。
结合 STE 和自己的开发经验，我写了 hai-simplified-technical
https://github.com/hylarucoder/hai-stack/blob/main/skills/hai-simplified-technical/SKILL.zh_CN.md
hai-simplified-technical 包含技能说明、中英文规则文件、检查脚本和交付模板。Agent 加载这个技能后，按五步写或改技术文档：
-
判断范围：确认这是技术文档。
-
找项目约定：先找术语表和写作规范。项目约定和规则冲突时，以项目为准。
-
写或改：按规则改措辞，事实、条件和风险原样保留。
-
机械检查：运行 check.py。
-
交付：交出文档，简述修改和检查结果；需要作者确认的证据、风险或内容缺口，另外列出。
其中有两个设计决定。
第一，check.py 只报出要看的地方，不替你判断。引用的例子、紧挨代码名的写法、有理由不守的软规则，都可以不改。反过来，脚本没有报错，也不代表已经查清代词指向、事实真伪和所有规则。
第二，缺的证据写进交付说明，不写进正文。原文写“性能也有了显著的提升”，但没有数字。技能只删掉“显著的”，不在正文里插一个“[待补]”，更不会编一个数字。只有读者缺了这个信息就没法操作时，才在正文里标出来。其余缺数据的说法，交付说明里列给作者。
这就是第九句：面对缺口，拒绝编造。
边界：它不写营销文案
这套规则只管技术文档：设计文档、README、API 文档、runbook、迁移指南、PR 描述、代码注释、错误信息。
营销文案、发布帖子、演讲稿，它不碰。这些文字靠节奏、情绪和修辞打动人，套上规则会变得干瘪。发布说明这类混合文档，只改技术部分：改了什么、怎么升级、哪里不兼容。
技术文档先让人读准。 介绍文章还要让人愿意读下去。
所以，这篇介绍保留了比喻和节奏。它介绍这套规则，并不把整篇文章当作技术操作手册来改。
三 · 效果
最近写了一个自用的视频编辑器，在 opus 5.5 / astra 6/ grok 4.7 轮番轰炸之后，文档阅读体验已经相当差，而解决一些很细的问题又必须要多读文档才能驱动 agent 继续工作。 用了这个 skill 之后阅读体验好太多了。
以下是对比
如何使用？你只需要把这个地址复制给你的 coding agent 就行。
安装这个 skill https://github.com/hylarucoder/hai-stack/blob/main/skills/hai-simplified-technical/SKILL.zh_CN.md，帮我看下 xxx 相关的文档，优化一下表达。
强烈推荐大家试试，如果有帮助记得点赞转发，感激不尽！
参考资料
-
STE 的来历：ASD-STE100 官网
-
《Python 之禅》：PEP 20 – The Zen of Python
-
github.com/hylarucoder/hai-stack
