从代码生成文档:AI 做对了什么,又做错了什么

作者: Fraser Hardy

代码编辑器和正在运行的应用窗口,共同生成一篇带编号步骤和截图的帮助文章草稿,再由审阅者标记为已核对

把模型指向一个代码仓库,要求它生成帮助中心,它真的会给您一个。看上去像是已经完成了。然后您读到第四篇文章,发现它正在向您的客户介绍 PlanTier.PRO_LEGACY,还有一个位于 /admin/impersonate 的页面。

那么,AI 能从代码生成文档吗?能,而且草稿很有用。AI 擅长找出每一项功能、把按钮名称写对,并产出风格统一的初稿。但直接从模型输出的内容,稳定地会在三件事上出错:泄露内部术语,记录用户根本看不到的页面,以及描述的是代码,而不是用户想要完成的任务。解决办法是让草稿以正在运行的应用为依据,并在发布前由真人审阅所有内容。

下面讲讲原因,以及怎样搭建流程,让产出的内容值得发布。

两种截然不同的“从代码生成文档”

人们搜索这个话题时,指的是两件不同的事,值得分开来讲。

开发者参考文档。 API 参考、SDK 文档、函数签名。这基本上是个已经解决的问题,根本不需要 AI。TypeDoc、Sphinx autodoc、Javadoc,以及 Swagger UI 这样的 OpenAPI 工具,会读取您的代码或规范,确定性地生成参考页面。它们枯燥而可靠,而这正是您对参考文档的期望。

用户文档。 面向永远不会看到您代码的人的帮助中心文章:“怎么导出我的发票”“怎么添加队友”。这是难的那一种,也是 AI 文档生成工具如今真正有用、也真正有风险的地方。

本文讲的是第二种。如果您需要的是 README 或代码注释,您的编程助手已经做得足够好了。

AI 从代码生成用户文档时做得好的地方

该肯定的要肯定。模型阅读代码库,在几项具体的工作上比人做得更好。

它能找出所有功能

人写文档靠记忆,而记忆会遗漏功能:八个月前某人做的 CSV 导入,那个键盘快捷键,那个只在团队套餐里才出现的设置。模型读取您的路由文件、导航组件和表单,就能生成一份完整的清单,光这份清单就值得做这件事。大多数帮助中心都有没人知道的空白。

它能得到准确的标签

按钮文字就在代码里:"Export CSV"、"Send invite"。模型会原样引用,而人写的往往是“点击导出按钮”,让读者自己去猜。

它能注意到限制和规则

校验规则存在于代码里:项目名称的最大长度、文件大小上限、让按钮变灰的角色检查。这些恰恰是会引发支持工单的细节(“为什么我保存不了?”),也恰恰是人类撰写者不了解的细节。

AI 从代码生成文档时出错的地方

这是大多数工具不会放在落地页上的部分。根据我的经验,这些问题几乎出现在每一份原始的 AI 草稿里。

1. 内部术语泄露

您的代码和界面用的是不同的词。数据表叫 workspaces,界面上写的是“团队”。枚举值是 PlanTier.PRO_LEGACY,定价页上写的是“Pro”。这个功能在内部叫了一年 smartRouting,之后市场部才把它命名为“自动分配”。

模型读的是代码,所以用的是代码里的词。您会得到这样的句子:“在团队页面创建一个新的工作区(org)”,这对客户来说令人困惑,而且也不对。更糟的是,它还会泄露您从未打算公开的名称。

2. 它记录了用户看不到的页面

模型看到一条路由,就为它写一篇文章。它完全不知道:

于是它为所有这些都写了帮助文章。最好的情况是,客户去找对他们根本不存在的页面,然后给您发邮件;最坏的情况是,您公开了自己的路线图,或者一篇关于管理员代登录工具的操作指南。

3. 它描述的是代码,而不是用户的任务

这是最微妙的一种,也是最常见的一种。模型解释代码做了什么,因为它面对的就是代码。而用户并不关心代码做了什么,他们想把事情办成。

左右对比:左边是 AI 草稿,解释 InvoiceExport 组件、它的 API 端点和一个管理员路由;右边是改写后的版本,标题为“下载您的发票”,只有三个通俗的步骤和一张截图

左边的版本是准确的,但对一个会计刚刚索要上季度发票的人来说毫无用处。右边的版本从目标出发,使用屏幕上的词汇,并指出该点哪里。Diátaxis 框架很好地划清了这条界线:操作指南服务于一个目标,参考文档则描述机制本身。即使您要求的是操作指南,原始的 AI 草稿也会滑向参考文档。

4. 对代码无法确定的行为,它自信地乱猜

用户体验到的很多内容,并不完全由代码决定。确认邮件是否真的发出,取决于配置;一个页面长什么样,取决于其中的数据。您的退款政策、客服时间,以及取消订阅后数据的处理方式,通常根本不在代码仓库里。

模型会用听上去合理的猜测来填补这些空白,语气与其他一切内容一样自信。这才是危险之处:错误的句子看上去与正确的没有任何区别。

为什么文档要以正在运行的应用为依据

代码告诉您什么可能存在,而正在运行的应用展示的是用户实际看到的东西。

如果您只凭代码生成文档,您记录的只是关于产品的一套理论。运行应用,以普通套餐的普通用户身份登录,上面的大多数问题就会缩小:

您可以借助浏览器自动化工具自己来做。一个最简化的 Playwright 脚本,以演示用户身份登录并为一篇文章捕获某个页面,大致如下:

// docs/capture/billing.spec.ts
import { test } from '@playwright/test';

test('capture billing page for the invoices article', async ({ page }) => {
  await page.goto('http://localhost:3000/login');
  await page.getByLabel('Email').fill('docs-demo@example.com');
  await page.getByLabel('Password').fill(process.env.DOCS_DEMO_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();

  await page.goto('http://localhost:3000/settings/billing');
  await page.screenshot({ path: 'docs/img/download-invoices-step-1.png' });
});

Playwright 截图文档介绍了仅元素截图和整页截图。难点不在脚本,而在于要有看起来真实的预置演示数据,以及一个能在 CI 中正常工作的登录。完整的搭建过程,我们在如何自动创建产品截图中有详细介绍。

为什么人工审阅仍然不可省略

即使有了良好的依据,每一篇文章在上线之前,也必须由了解产品的人阅读一遍。不是扫一眼,而是认真读。

下面是我会交给审阅者的检查清单:

  1. 用词与界面一致。 每个功能名称、按钮和菜单项,都是客户看到的名称,而不是工程师的叫法。
  2. 每个页面都能到达。 这篇文章面向的套餐上的客户,确实能到达那里。特定套餐的功能要明确注明。
  3. 从任务出发。 标题是用户会在搜索框里输入的内容。第一步是一次点击,而不是一大段背景介绍。
  4. 政策是真实的。 任何涉及金钱、数据、取消订阅或客服时间的内容,都来自您,而不是模型。
  5. 没有未发布的内容。 没有内测功能,没有内部工具,没有市场部尚未公布的名称。

审阅一份像样的草稿,比从空白页开始写要快得多,这正是关键所在。但正是这一步,把一份看似合理的草稿变成了您愿意为之负责的文档。如果跳过它,您就是在以公司的名义发布模型的猜测。

从代码生成文档的六步流程:阅读代码,过滤掉管理员页面和受功能开关限制的页面,运行应用并捕获截图,撰写基于任务的文章,人工审阅,然后发布,并在代码变更时重新检查

您可以用编程助手完成的自助工作流

要获得大部分价值,您并不需要专门的 AI 文档生成工具。借助 Cursor、Claude Code、Copilot 或类似工具:

1. 先要清单,不要文章。 可以这样问:

List every user-facing feature in this app. For each one give:
- the route or screen where a user finds it
- the exact button/menu labels involved
- any plan, role or feature-flag check guarding it
Do not write documentation yet.

2. 手动精简。 划掉管理员路由、内部工具、受开关限制的内测功能和废弃代码。这大约只需十分钟,却能避免最严重的错误。

3. 给它一份术语表。 一张简短的清单,把代码术语对应到界面术语(workspace → Team,PRO_LEGACY → Pro)。把它粘贴到每一次起草的提示词里。

4. 每篇文章只写一个任务。 要求它为非技术用户写一篇操作指南,只使用清单中的标签,从目标开始,并用 [CHECK] 标出任何它没有把握的句子。

5. 走一遍应用并截图。 亲自按每篇文章操作一遍,改正错误,添加截图。

6. 对照上面的清单审阅,然后发布。 在结构方面,如何撰写人们真正会用的帮助中心文章提供了一个很适合这里的模板。

自助路线的弱点是第 7 步,而它目前还不存在:当下周的一次代码变更让第十二篇文章变得不准确时,及时发现这件事。这是另一个独立的问题,在如何让文档保持最新中有专门讲解。

Ellie Docs 如何处理这些问题

我们围绕上述这些出错的情形构建了 Ellie Docs,下面是它的对应方式。

它读取您的代码仓库,梳理功能和面向用户的页面,然后按用户要做的事情组织,起草一个帮助中心。

Ellie Docs 的内容树,显示从代码起草的帮助中心,包含“入门”和“改进 Ellie 的回复”等分区,每个分区下是以任务命名的文章

它在沙盒中运行您的应用,捕获已登录产品的真实截图,并放进文章里。每篇文章都会显示它所依据的功能,因此当这些功能在代码中发生变化时,Ellie 就知道这篇文章可能受到影响。

Ellie Docs 文章编辑器,显示一篇已发布的文章,其中有自动捕获的应用截图,旁边是列出关联功能的“依据”面板和显示捕获结果的“截图”面板

每个合并的 PR,它都会检查变更涉及哪些文章,并以差异对比的形式提出修改,由您接受或忽略。当它根据已合并的 PR 撰写您的更新日志时,会暂缓收录未发布或受功能开关限制的工作条目。没有任何内容会自动发布,发布由您来做。

某个拉取请求之后对帮助文章的建议更新,以红绿差异对比的形式显示,用新的“可用时间”设置步骤替换过时的步骤,带有“忽略”和“接受”按钮

它有时仍然会出错。它无法知道您的政策,偶尔也会选了代码里的词而不是界面里的词。这就是为什么每一份草稿和每一条建议都要经过您。如果您的应用是用 AI 构建工具做的,为 vibe coding 应用编写文档的指南介绍了这方面额外的注意事项。

人们常问的几个问题

有免费的 AI 文档生成工具吗? 您的编程助手加上上面的自助工作流,不需要额外花钱。如果您希望由工具来处理截图和更新追踪,Ellie Docs 也有免费方案,无需绑定银行卡。

没有 OpenAPI 规范,AI 能生成 API 文档吗? 可以,它会读取您的路由处理程序。如果您已有规范,请使用 Swagger UI 或 Redoc 之类的标准工具,它们是确定性的,而且免费。Ellie Docs 在其 Growth 套餐中,可以不依赖规范,直接从代码生成 API 参考,对于从未写过规范的团队很有帮助。

应该让 AI 自动发布文档吗? 不应该。让它起草和提出建议,由了解产品的人批准客户将会阅读的一切内容,尤其是涉及账单或数据的部分。

AI 撰写的文档准确吗? 准确程度取决于其依据和背后的审阅。仅凭代码,预期得到的是一份有用的草稿,其中夹杂着自信的错误;以正在运行的应用为依据、并由了解产品的人审阅之后,它们可以比大多数团队手写的更好,主要是因为它们覆盖了人类遗忘的功能。

如果您想要以真实应用为依据的草稿,附带截图,以及逐个 PR 提出、由您批准的建议,免费试用 Ellie Docs。连接一个代码仓库,今天就审阅您的第一个起草好的帮助中心。