规模化文档:与 Andrew Etter 畅谈——《现代技术写作》出版十年之后
纯音频版
点击收听:
相关链接

- Documentation at Scale: Best-in-class content for the AI era(Andrew Etter,Amazon — Kindle 电子书,Kindle Unlimited 会员也可阅读)
- Modern Technical Writing: An Introduction to Software Documentation(Andrew Etter,Amazon — 他 2016 年的著作)
- Andrew Etter《Modern Technical Writing》电子书书评(Tom Johnson,I'd Rather Be Writing — 2016 年的书评)
- 录像:Andrew Etter 讲《Modern Technical Writing》(STC 硅谷分会)(Tom Johnson,I'd Rather Be Writing — Andrew 2017 年的演讲)
- 技术传播领域六本新书盘点(Tom Johnson,I'd Rather Be Writing)
- 为什么文档仍需负责人——与 CT Smith 探讨 WTFM 的播客(Tom Johnson,《I’d Rather Be Writing》——关于文档归属权的前一集)
- 概览 | 文档 - Roblox 创作者中心(Roblox 的创作者文档)
- Markdoc | 一个强大、灵活、基于 Markdown 的写作框架(文中讨论的 Markdown 变体)
- Daring Fireball: Markdown(John Gruber——最初的 Markdown 语法及其可读性目标)
- xkcd: 标准(Randall Munroe——“现在有 18 种标准”笑话背后的漫画)
- 随着 AI 加速,技术写作者的孤立与孤独感可能会加剧
本集播客涵盖的主题
以下是我们聊到的话题列表。注:这些 Shownotes 由 AI 生成。
-
为何在《现代技术写作》出版十年后推出第二本书——第一本书是 Andrew 想递给新员工的,却在书店里买不到。《规模化文档》汇集了他在大型和小型公司学到的经验,涵盖流程、团队结构,以及在大型组织中运作的要点,而不仅仅是工具。为了能够持续更新,该书仅提供 Kindle 版。
-
Markdown 的简洁性及其变体失去的东西——Markdown 之所以获胜,是因为公司里的任何人都能用它做出贡献,而没有任何开发者会去打开 DocBook 文件。AI 对 Markdown 的偏爱虽未可预见,但也不令人惊讶。Markdoc 和 MDX 等变体重新引入了 Markdown 原本旨在摆脱的花括号和晦涩标签。
-
为 LLM 提供的 Markdown 镜像页面——源 Markdown 文件中包含大量变量、提示框和前置元数据,这些内容难以直接传输给 LLM。一条可行的流水线是将源文件转换为 HTML,再将 HTML 主体转回干净、极简的 Markdown 文件,同时解析变量并移除前置元数据。
-
集中式文档团队的业务价值——核心在于成本、责任和质量,其中“责任”最打动管理层。一款顶级产品总得有人在负面推文出现时站出来负责。文档工程师即使不亲自写多少内容,也能推动文档整体发展,而把 20% 时间投进来的开发者做不到这一点。
-
为什么工具浪潮始终没能取代写作者——Wiki、Web CMS、Markdown,乃至如今的 AI,每一次都引发过“写作门槛降低,行业要完了”的担忧。但它们都没解决内容所有权的问题。贡献者提交完内容就当甩手掌柜,所以测试基础设施必须能捕捉到 18 个月后失效的代码示例。
-
为不想学工具的贡献者做的 Slack bot——有些 PM 和市场营销人员觉得 Git 很吓人,还有些人干脆想让别人代劳。一个能从自然语言请求直接开 PR 的 Slack bot 正好同时满足这两类人。为了搞定权限和公司上下文,迭代了三个版本,目前最大的摩擦点反而是没有 GitHub 账号的人。
-
Bot 开的 PR 是一种协作式写作——人开 PR 时,每次修改都得经由这个人返工;bot 开 PR 时,Slack 线程里的任何人都能引导它,包括发起请求的人、文档工程师,或被拉进来提供意见的 PM。让 bot 批量处理文档 bug 积压任务时,节奏控制在每天六条左右效果最好。
-
AI 是转移工作,而不是减少工作——有的公司用 AI 裁减人手,有的用它做更多的事,但预期普遍水涨船高。AI 让全量文档审计变得可负担,能在 PR 审查中抓出拼写错误和时态问题,还能替代 Postman 来测试 REST 接口。省下来的时间则用于内容之间的衔接、用例、视频和博客文章。
-
AI 仍然不足的地方:教程和视频——指南要求全面覆盖,但教程讲究恰到好处的省略,而 AI 往往塞得太满。API 描述通常需要删减到模型产出的一半左右,身份验证则是教程里经典的坑。视频剪辑依赖精确到帧的剪切,目前还是手动在 Premiere 里做更快。
-
用 AI 让文档更好看 — Stripe 的文档之所以被奉为行业标杆,很大程度上是因为其出色的视觉呈现,即便是一些很少使用它的人也会如此认为。AI 极大简化了前端工作,设计师只需提供几张静态图片,而非完整的 CSS 文件,写作者便能在不到一小时内完成重新设计并发布。
对话的叙事性文章版本
如果把这档播客变成一篇文章,内容应该是这样的。
负责你未撰写的内容
在大型文档站点中,技术写作者可能并没有撰写大部分文字,这一现象在 AI 出现之前就很普遍了。在 docs-as-code 模式下,开发者通过 Markdown 贡献内容,写作者的工作重心早已转向审阅来自外部的内容、修正问题,并判断其是否达标。换言之,写作者是在管理文档,而非撰写其中的每一个字。AI 将这一趋势推得更远,但并未改变其基本形态。
这一点值得牢记,因为该领域长期存在预言自身将被淘汰的历史。当 Wiki 出现时,人们担忧如果任何人都能编辑页面,就不再需要写作者了。同样的担忧在基于 Web 的内容管理系统、嵌入开发者工作流的 Markdown 出现时再次浮现,如今更是随着能凭一行请求生成页面的 AI 工具重现。
这些工具都让创作变得更容易了。然而,它们都没有回答一个核心问题:谁对整体文档负责?谁会发现某页内容过时?当不满的用户发帖抱怨指南存在错误时,谁接到电话?谁定义质量标准,并用哪些指标来衡量文档的效果?
这些问题指向了设立集中式文档团队的根本原因,其支柱在于成本、责任和质量。三者之中,责任(accountability)最能打动管理层。如果没有人愿意为文档负责,产品就不可能成为行业最佳;仅靠少数开发者在业余时间打理文档,是无法达到这一目标的。
贡献者往往在提交内容后就觉得自己和它的关系到此为止了。开发者写完某个功能的文档,就转到别的项目去了,直到 18 个月后某个 API 被弃用,才会重新想起那个页面。给其他团队的代码仓库贡献过代码的人都知道这种感受——默认假设是负责的团队会去测试、发布和维护。文档贡献也是一样,所以必须有人来为接手的内容负责。
归属问题解决之后,工具的选择就更有意思了。Docs-as-code 的假设是贡献者会学会用文本编辑器和 Git,很多开发者确实如此。但产品经理和市场营销人员大多不会,有些人甚至根本不想用工具——他们只想说出需要改什么,然后让别人去做。一个接收需求并自动发起 pull request 的自由文本 Slack bot 很好地满足了这种需求,剩下的主要障碍只是有些人从未注册过 GitHub 账号,无法审阅结果。
由 bot 发起的 pull request 还有一个容易被忽视的好处。当某个人提交 PR 时,只有他本人能修改,每条评审意见都得绕回到他那里。而当 bot 创建 PR 时,Slack 会话里的任何人都可以推动修改,无论是提出需求的人、技术作者,还是被拉进来提供第二意见的产品经理。Bot 把单作者的交接变成了更接近协作创作的东西。
AI 也改变了技术作者时间的去向,尽管工作量可能并没有减少。有些公司认为可以少招人,有些公司则发现自己能做更多事——而预期往往会随着工具一起增长。
先消失的是繁琐的工作。AI 审校者可以在人工介入之前就标出几十处拼写错误,或者揪出通篇使用将来时态的页面。以前需要一群人做枯燥工作才能完成的全量文档审计,现在成本也变得可接受了。测试 REST 接口不再意味着打开 Postman、在终端里转义引号,因为 agent 可以逐一调用所有接口,并把响应与文档做比对。剩下的是更高层次的工作,比如页面之间的衔接、用例,以及视频、博客文章这类补充内容。
不过这也有局限,局限恰恰出现在最需要判断取舍的地方。AI 倾向于写太多内容。哪怕是一段简单的 API 描述,可能也得砍到模型输出的一半左右。
教程的问题更明显,因为好的教程有赖于精心的省略。鉴权就是典型例子。模型会把鉴权的全部复杂细节都塞进教程里,而人类作者则会告诉读者先用最简单的方案,再附上详情链接。
视频剪辑也有类似问题。一次剪辑