ARTICLE · 1106210
用 AI 写技术文档的工程师:写得更快,写得更差
现在很少有工程师从零写技术文档了：把背景贴给 AI，一段对话生成一节，哪里缺了让它补一段，图也是它配的，很快一份又长又全的文档就完成了。发出去之后没人提意见，收到的回复往往是「挺全面」——但那不是认可，是读者投降了。
一份技术文档唯一要完成的任务，是让读者不需要来问作者。按这个标准，这类文档是失败的：读者要么压根没读完，要么读完什么也没记住，最后不得不走到作者工位前当面去问。
值得说明的是，这类作者的判断力并不低——他们敢在文档里承认哪里没想清、哪里做不到万无一失，愿意这么写，本身就说明思考是认真的。他们的问题不在脑子，而在于从来没把「写」当成一门手艺；AI 来了之后，这门手艺连练的必要都像是没有了。
最先暴露出来的一点是：这些文档从头到尾只有作者一个人的视角。
一、文档是写给自己的，不是写给读者的
文档里散落着只有作者自己需要的东西：某段只有他能看懂的记号、某条「应谁的要求删掉了什么」的备忘。那不是读者的信息，是作者的记忆。他缺的从来不是表达能力，是「读者是谁」这根弦。
二、用「写全」冒充「写清」
怕遗漏，于是只增不删：决策补一节，两个方案都写上，每个环节配一张图。在他的标准里，覆盖等于严谨。但严谨里最贵的那部分恰恰是压缩和取舍——决定不写什么，和决定怎么简化设计，是同一种能力。写全了只是写齐了，写清了才是写对了。
三、对代码从不手软，对文字从不负责
工程师绝不会把一个边改边修、没人看过、根本没跑通过的程序交付出去，但他们在文档里干着完全一样的事，而且毫无不适。因为在他们的世界里，代码是交付物，文档是副产品。副产品不需要被打磨、被检查、被追责——他们从来没觉得文档需要这些。
四、文档写在错误的时点
一份好方案最大的价值，是在动手之前便宜地犯错：被质疑、被推翻，只改文字不付代价。而多数人的文档是事后补写的——事情已经做完，谁也没法再推翻什么，此时的文档不再是用来对齐的约定，只是既成事实的记录。他们从没在有用的时点写过文档，所以从没拿到过回报，于是断定写文档是浪费。不是文档没用，是他们没赶上它有用的时候。
五、长，是因为不敢短
篇幅膨胀的真正原因常常不是内容多，而是决定没做。两个方案拿不定，就都写上，再补一段「该怎么读」；结论下不了，就写「待定」、「建议」、「需进一步确认」。每一处含糊，都是一次把判断的责任推给读者。敢写短篇幅的前提是敢下结论——结论先定下来，篇幅才减得下来。
六、文字没有机器把关
程序写错，机器当场报错，所以工程师对代码的失败有痛感。文字没有任何东西会报错，而且作者自己全都懂——「我懂了」和「我写清楚了」在他这里是同一个感觉，错误就永远不会浮出水面。他不是傲慢，是真的感知不到读者会在中途迷路。这里缺的是一个强制反馈：文档定稿前，找一个没参与的人，三十分钟讲懂——讲不懂的地方，就是没写清的地方。
七、没人读，于是写不好；写不好，于是更没人读
长文档天然逃过审阅：多数人打开几分钟就投降了，回一句「挺全面」。而一份短小、每一页都是硬结论的文档，反而无处可藏，必然被狠狠挑刺。有人尝过这个甜头之后，行为就定型了——写长等于安全。再加上组织里的一笔暗账：文档越没人看得懂，作者越不可替代。而把话写清楚这门手艺，在职业阶梯上很晚才被定价，于是没人练。
八、写的是笔记，不是方案
这种文档对作者本人有真实价值：日后回看，细节齐全，非常好用。但它被当成给团队看的方案发了出去，问题就出在这里。写给自己的笔记，目的是帮自己记住；写给别人的方案，目的是让别人看懂。两种目的需要两种写法，而多数工程师只写了前一种，还把它当成了后一种。
九、工具降低了写的成本，也降低了写好的动机
这种文档里到处是「聊一段、补一段」的堆积痕迹——AI 把这件事加速到了极致。当补文档便宜得像贴一张便利贴：缺一节，问一句就有了；少张图，再问一句也配好了，重写反而显得昂贵。于是文档只往上加，从来没有整体重写的那一天。工具降低了写文档的成本，同时也降低了写好文档的动机。AI 能替你把字写满，不能替你想清楚写给谁、为什么、不写什么。
结语
一句话概括这种状态：造东西的手艺接近资深，写文档的手艺停在入门。而这是最可惜的一档——思考密度那么高的内容，传达出去的可能不到三成。
个人能做的三件事：
1. 把「给外人三十分钟讲懂」当作验收：讲不懂，就不许归档。 2. 动手之前写，而不是做完之后写：让文档先替你犯错。 3. 定稿前删掉三分之一：凡是只有你自己才需要的记号，移到自己的笔记里。
组织能做的三件事：
1. 给文档配上读者和反馈：谁读、谁挑、多久挑完，像程序必须有人看过才能上线一样。 2. 别把篇幅当成绩：三页硬决策，胜过三十页覆盖度。 3. 别纵容「只有作者讲得清」：那不是作者的安全感，那是组织的负债。
AI 能替你把字写满，但「写给谁、为什么、不写什么」这三个问题，它一个也替你答不了。如果这三个问题没有答案，文档就只会更长，不会更有用。