开发者分享用AI起草软件文档的方法：像带实习生一样分配任务并审核

我最近在用 AI 起草软件文档。我把它当作实习生对待：给它分配任务、提供示例、检查它的产出，再说明哪里需要修改。无论是 AI 还是实习生，我都得把这些经验记录下来，供下次参考。

下面讲讲我是怎么用 AI 写软件文档的。

假设我要为一个新的安全功能写文档。我先从使用者入手，通常是安全管理员。我假定他们懂安全，但未必了解我们的产品。

他们想完成什么？他们已经知道什么？

在让 AI 起草之前，我必须先搞清楚这些问题的答案。

我从工程工单、产品需求、设计文档以及与开发者的交流中收集信息。这些来源并不总是一致。需求会变，有些决策也从来没有被好好记录下来。

我让 AI 标出信息缺口和相互冲突的地方，然后去核实那些真正重要的部分。

接着，我把我们的文档模板、风格指南和原始素材一起交给 AI agent。我要的是一份符合我们产品文档风格的草稿，而不是每个功能都另起炉灶发明一种新格式。

根据功能的不同，我会走一遍 UI、调用 API 或者运行脚本。我能完成任务吗？步骤准确吗？AI 有没有漏掉前置条件？产品的行为是否与描述一致？

有时我发现的是文档错误，有时发现的是产品问题，有时测试还会暴露出原始素材之外的细节。

这正是领域知识发挥作用的地方。

简单的修改我自己动手。没必要为了改一个 UI 标签或者删掉一句废话而去重写提示词。

但如果 AI 漏掉了前置条件，我就会更新 agent 的指令，让它去检查这些条件。然后我再要一版草稿，看看改动是否奏效。

这让我想起带实习生的经历，或者，带一个叛逆期青少年的经历。一个错误我可以解释一次，但用 AI 的时候，我得把解释写进指令里。否则，下一份文档里可能还是同样的错误。

一旦我对草稿满意，就把它发给领域专家（SME）审阅。

我对产品足够了解，能解释功能、也能对有问题的建议提出质疑。SME 也会犯错。我会请他们核实我自己无法确认的细节，比如不常见的边缘情况或实现上的限制。

审阅之后，我做最后的修改并发布。

AI 承担了可重复的工作，包括在文档之间复制信息。这省下的时间，我可以用来理解产品、帮助用户。

我不是在教 AI 做我的工作，而是在教它处理可重复的任务。我也会用它对照我们完整的风格指南来检查我的工作。