每周发布版本时,如何让文档保持最新

作者: Fraser Hardy

一个已合并的拉取请求,带有红绿差异对比行,一个箭头指向某篇帮助文章,其中对应的步骤被高亮出来,等待审阅,旁边有接受和忽略按钮

一位客户发来邮件:“您的指南说先进入设置,再进入日历,但根本没有日历。”他们说得对。六周前您把它挪到了“账户”里。这个 PR 经过了审阅、测试和发布,而帮助文章没有改,因为没有人的职责是去改它。

几乎所有过时的文档都是这样产生的。不是因为懒惰,只是“我们改了产品”和“这些文章描述的正是我们改动的那部分”之间,缺少一个关联。

要在每周发布版本时让文档保持最新,就把文档纳入拉取请求:每个 PR 都要回答“这次变更会改变客户看到的内容吗?”,写明它影响了哪些帮助文章,并在同一个 PR 或与之关联的 PR 中提交文档修改。 然后把机械性的部分自动化(截图、更新日志条目),并通过观察支持工单和帮助中心的搜索,找出漏网的偏差。

本文其余的部分,讲的是如何在不雇用技术文档工程师的情况下把这一切搭建起来。

为什么文档会过时

文档偏离现状有几个可预见的原因,而“让我们更仔细一点”解决不了其中任何一个。

文档放在别处。 代码在 GitHub,文档在 Intercom、Zendesk、Notion 或某个 GitBook 空间里。没有任何东西把其中一边的文件与另一边的页面联系起来,所以一边的改动永远不会促使人去看另一边。

知情的人不是写文档的人。 挪动日历设置的工程师确切地知道改了什么,而维护帮助中心的人,是从客户那里才知道的。

文档是成批修复的。“我们会在季度末做一次文档梳理。”与此同时,每一次每周发布,都在侵蚀准确性,而大规模的重写耗时太久,等它发布时已经部分过时了。

没人知道哪些文章受到了影响。 即使是积极的团队,也无法在每次发布后检查 80 篇文章,于是他们一篇也不检查。

示意图:文档随时间偏离现状的情况。季度重写的那条线在每次每周发布后下降,只有在重写时才会回升;而逐个 PR 更新的那条线则始终接近准确

这个模式与其他任何维护工作一样:小而持续的更新,胜过周期性的英雄式突击。

把文档纳入“完成”的定义

最有效的一项改变:在您的拉取请求模板中加入文档部分。只要在 .github/pull_request_template.md 放一个文件,GitHub 就会在每个 PR 上预先填入它(GitHub 的 PR 模板指南)。

## Docs impact

- [ ] This changes something a customer can see or do
- Help articles affected: <!-- slugs or links, or "none" -->
- [ ] Screenshots need re-capturing
- [ ] Changelog entry drafted (or marked "internal only")

带有“文档影响”部分的拉取请求模板:复选框分别询问变更是否对用户可见、涉及哪些帮助文章、截图是否需要重新捕获,以及是否已起草更新日志条目

大约两周内,它会让人觉得像是官僚作风。然后它会变成这样一个时刻:工程师在背景还很新鲜的时候,说一句“哦,新手引导的文章里提到了这个页面”。由做出变更的人写下的两行文档修复,胜过一个月后凭猜测写出的完美修复。

有两条规则能让它坚持下去:

  1. 审阅者要检查这个复选框。 如果某个 PR 明显改变了界面,却写着“无文档影响”,审阅者就要问为什么。就像缺少测试一样。
  2. 文档的修改可以粗糙一些。 工程师不需要写出润色过的文字。“第 6 步改为:打开账户,然后进入可用时间设置”就够了。措辞可以稍后由别人来整理。准确性第一。

把帮助文章对应到它所描述的代码

PR 检查清单依赖于人们记得有哪些文章存在。用一份从代码路径到文章的简单映射来帮助他们:

# docs-map.yml
- paths: ["src/features/calendar/**", "src/pages/accounts/availability*"]
  articles: ["connect-your-calendar", "set-your-availability"]
- paths: ["src/features/billing/**"]
  articles: ["change-your-plan", "update-payment-method", "download-invoices"]
- paths: ["src/features/onboarding/**"]
  articles: ["get-started"]

然后,一个小型的 CI 步骤读取变更文件列表(git diff --name-only origin/main...HEAD),与这些通配符进行匹配,并在 PR 上发表评论:“此 PR 涉及日历代码。请检查:connect-your-calendar、set-your-availability。”这大约只需 40 行脚本,却能把“想想文档”变成一份具体的、可以点击的清单。

当然,这份映射本身也会过时。把它放在代码旁边,每当有人写了新文章就加上一行。它仍然比维护文档本身容易得多。

如果您的文档与代码在同一个仓库中(使用 Docusaurus、Mintlify 或 GitBook 的 Git 同步等方式实现的“文档即代码”),您还可以更进一步:在文档文件夹上设置 CODEOWNERS 条目,确保有关心文档的人审阅其中的每一处改动。

写出腐烂得更慢的文档

有些写作上的选择,能让文档维护轻松得多:

关于结构的更多内容,请看我们的指南:撰写人们真正会用的帮助中心文章。

把机械性的部分自动化

有些文档维护需要判断,但很多只是脚本做得更好的杂活。

截图。 手动重拍图片,是最先应该自动化的事情。针对预置了数据的演示账户编写 Playwright 脚本,并在 CI 中运行,每次合并都能得到新鲜、一致的图片。完整的脚本在如何自动创建产品截图中有详细讲解。

更新日志条目。 您已合并的 PR 本来就描述了发布的内容。把它们变成面向客户的更新日志,主要是把工程师的语言改写成平实的语言,并按“新增、变更、修复”分组,这是由 Keep a Changelog 推广开来的惯例。模板请看如何撰写客户会读的更新日志。

视频。 如果您有演示视频,同样的代码路径映射也能告诉您哪些需要重新录制。把画面和配音分开录制,能让重做变得很快;产品演示视频的制作流程在这里。

找出您已经存在的偏差

即使流程很好,仍然会有一些变更漏网。下面这些信号能告诉您漏在哪里:

不要记录尚未发布的内容

快速迭代的团队有一个陷阱:某个 PR 在功能开关之后合并了,有人尽职地更新了文档,于是帮助中心现在描述的是大多数客户看不到的功能。客户感到困惑,客服收到了工单。

对于受功能开关限制的工作,文档的修改要等到该开关对所有人开启之后再提交(或者先写成草稿,随着逐步放量一同发布)。更新日志条目也是如此。

有助于文档维护的工具

Intercom、Zendesk 和 Help Scout 这类服务台,都有相当不错的帮助中心编辑器,但它们完全不知道您的代码里有什么,所以上面所有的关联都要靠您自己。GitBook 和 Mintlify 这类“文档即代码”平台把文档存放在 Git 中,从而获得 PR 审阅和历史记录,当您的撰写者习惯使用代码仓库时效果最好。较新的 AI 优先的帮助中心工具,包括 Ferndesk,正试图从其他角度弥合这一差距。

我们专门围绕 PR 这一环节构建了 Ellie Docs。您连接一个 GitHub 代码仓库,Ellie 会梳理您的功能,并把每篇帮助文章与它所描述的功能关联起来。每个合并的 PR,它都会检查这次变更影响了哪些文章,并以可审阅的差异对比形式提出修改,附上简短的原因说明。您逐条接受或忽略。没有任何内容会自动发布。

Ellie Docs 在某个 PR 合并后,针对“连接您的日历并预览可用时间”这篇文章给出的建议更新,红色删除线标出过时的步骤,绿色标出新的步骤,另有“接受”和“忽略”按钮

它还会根据同样的已合并 PR 起草更新日志条目,对于仍位于功能开关之后的内容,会暂缓收录,直到它正式发布。

Ellie Docs 的更新日志页面,其中的条目由推送的代码起草,包括一个新的可用时间设置面板,每一条都链接到相关的帮助文章,可随时发布

本文中的所有事情,您都可以手动完成,许多团队也确实如此。Ellie 只是每一次都替您完成“这个 PR 影响了哪些文章,应该改什么?”这一部分。

常见问题

在小团队里,谁应该负责文档? 由一位指定的人负责整个帮助中心(通常是创始人或负责客服的人),但每位工程师都要对自己 PR 的文档影响负责。没有指定负责人的共同所有权,就等于没有负责人。

我们应该多久审阅一次文档? 变更持续审阅(通过 PR 检查清单),再加上每月对访问量最高的文章做一次逐篇点击检查。每个季度的大规模重写,说明持续审阅的那部分并没有落实。

对面向客户的帮助文档来说,“文档即代码”值得吗? 如果撰写的人是工程师,值得。如果大部分内容由客服或市场团队撰写,那么普通的帮助中心编辑器,加上 PR 检查清单和一份文档映射,通常比强迫所有人使用 Git 效果更好。

如果我们的文档已经严重过时,最快见效的办法是什么? 修复访问量最高的 10 篇文章,添加 PR 模板,并开始给提到文档的支持工单打标签。这能在您着手处理长尾内容之前先止住出血。

如果您希望在每个 PR 上都有人替您提出文档修改建议,免费试用 Ellie Docs。连接一个代码仓库,得到一个起草好的帮助中心,并在发布的同时审阅建议的修改。