跳到主要内容

开发AI文档助手教会我的技术写作心得

· 阅读需 9 分钟
Pedro Vega
技术撰稿人 | 用户体验撰稿人 | 内容设计师 | 纽约客

大多数技术作家并不开发AI代理,我们为它们写文档。我们参加冲刺评审,阅读架构决策记录。然后想办法向那些只求周五前把集成跑通的人讲清楚检索管道是怎么回事。

可我还是做了一个。

他叫 Artie,一个用 Algolia 构建、运行在这个文档站点里的AI文档助手。做他的过程让我对写作与AI的关系,比听任何会议演讲都学得多。

本文不复述Artie的设计,那是**案例研究**的事。本文谈的是更广泛的几点:

  • AI代理究竟是什么
  • 检索增强生成在实践中如何运作
  • 为什么提示工程比多数人以为的更接近技术写作
  • 这些对我们这个行当的人意味着什么

什么算AI代理,什么不算​

人们把"AI代理"这个词安在从拼写检查到自动补全的一切东西上。区别很重要。并非所有AI功能都是代理。用机器学习的拼写检查不是代理,自动补全建议也不是。一个按固定决策树走的聊天机器人,不过是带文本框的流程图。

AI代理是指能在限定环境内理解目标并据此行动的系统。受约束的自主性把代理和提示—响应循环区分开来。代理读取上下文、选择策略,有时要走上好几步。

那么Artie在这条谱系上站在哪里?

按这个定义,他不是代理。他不浏览网页、不运行代码,也不串联多步工具调用。Algolia 在模型运行之前就把页面取回来了,模型只是把页面当作上下文接收。但他确实自己判断意图,也自己执行防护栏。他会在回答之前分辨这是技术问题还是作品集咨询。这比带文本框的搜索框多,比能根据用户提问提交缺陷报告的全自主代理少。

技术作家现在就需要这个区分。理解AI工具和AI代理是工作的一部分。为AI产品写文档时,你得知道它在这条谱系上的位置。然后你要向用户说明这个产品里"AI"意味着什么,因为他们的期待各不相同。

检索增强生成如何运作​

检索增强生成(RAG)支撑着Artie,也支撑着越来越多的AI文档工具。RAG 绕开了大语言模型(LLM)的一个根本限制。模型在固定数据集上训练,你的内容并不在训练数据里。

标准的LLM交互是这样的:用户发一个提示,模型用训练数据生成回答。这对通用知识够用,对特定领域的问题就不行。拿产品 API 去问基础模型,它要么编一个答案,要么干脆拒绝。

RAG 在用户提问和模型回答之间插入一个检索步骤。整个管道如下:

  1. 查询处理。 检索层把用户的问题转换成向量嵌入,也就是用数字表示它的含义。
  2. 检索。 系统在知识库里查找含义相近的内容。这里的知识库是用你的文档预先建好的索引。排序取决于含义,通常还会结合关键词匹配。"如何设置身份验证?"和"配置登录凭据"这两个查询会返回同一个文档页。
  3. 组装上下文。 系统把检索到的文档或文档片段,连同用户的问题和系统提示,一起打包进上下文窗口。模型随后处理这个包。
  4. 生成。 模型基于检索到的上下文而非训练数据生成回答。调校得当的系统里,模型会标明来源,也不会越出检索文档的内容范围。

流程图:用户提问依次经过查询处理、检索、组装上下文和生成,知识库为检索步骤提供输入

质量取决于第 2 步。检索层返回错误的文档,或者排序排得糟糕,模型再强也没用。它会用错误的材料写出一个看似合理、结构完整的答案。所以分块方式和嵌入模型的选择,比多数团队预想的更重要。功劳记在生成模型头上,质量却由检索层决定。

就Artie而言,知识库是这个站点的文档。Algolia 负责建索引和检索。Artie 只覆盖这里写过的内容,因此始终待在站点自己的材料之内。这种限制在实际中如何体现,**案例研究**里有说明。RAG 不会让模型更聪明,它让模型更负责,因为每个回答都挂在可核验的来源上。

提示工程就是技术写作​

这个项目给我上的最重要一课是:系统提示就是技术写作的交付物。

一个写得好的系统提示,包含的要素和风格指南一样。你定义读者。你设定语气和文风规则。你划定范围边界:系统该处理什么,不该处理什么。你写出足够精确、机器无需人工判断就能遵循的指令。你安排信息的顺序,让最关键的规则优先。

这份工作是读者分析,也是风格指南。它同时还是内容规划。

技能迁移几乎是逐项对应的:

  • 读者分析 → 读者分流。 技术作家识别读者并据此调整内容,系统提示对AI做的是同一件事。Artie 的提示在技术用户和招聘人员之间分流,就像结构良好的文档站点在不同读者画像之间分流。
  • 风格指南 → 人设校准。 每个文档团队都有语气和文风规范。系统提示就是给AI的风格指南。它按读者设定语气,并要求每个论断附上来源链接。
  • 信息架构 → 指令层级。 技术作家知道顺序和结构影响理解。指令放在哪里,会改变模型遵循它的程度。
  • 边界情况文档 → 防护栏设计。 好的文档会用清晰的指引覆盖意料之外的操作。好的提示设计会覆盖试图突破系统的用户。

不是每个技术作家都得变成提示工程师。这门手艺大量借用了技术作家几十年积累的技能。如果你能写出清晰、有结构、面向读者的文档,你对这份工作的贡献比你以为的要多。

防护栏是语言问题​

人们把AI安全当成技术问题:限流、登录、访问控制。这些都重要。但在公开的聊天机器人里,攻击者盯上的很大一部分是语言。

信息

提示注入是指用户覆盖系统提示。常见例子是"忽略之前的所有指令"这句话。

提示注入用语言绕过基于语言的控制。防御的办法是写出足够明确的规则,让攻击者无法说服模型越过它们。

Open Worldwide Application Security Project(OWASP)的LLM 应用十大风险清单把提示注入列为首要风险。读完那份清单你会发现,其中不少风险追根究底是语言问题:

  • 不当输出处理(模型输出什么)
  • 数据与模型投毒(模型从文本里学到了什么)
  • 过度自主(提示告诉模型它能做什么)

攻击手段是技术性的。防御往往写在系统提示里,用的是自然语言。

这就改变了技术作家看待安全工作方式的角度。没人指望我们去搭身份验证系统。但我们可以写出界定AI如何回应的规则,而且能写得足够精确,经得起对抗性输入。

文档工作会发生什么变化​

我不预言AI的未来。我可以描述当下可见的趋势,以及它对靠写软件文档谋生的人意味着什么。

AI文档助手已经从新鲜事物变成理所当然的期待。用户不再接受静态搜索。他们想随口问一句,就拿到有依据的回答,而不是十个蓝色链接。RAG 系统今天就能做到这一点,相关工具也越来越容易上手。

提示

对基础设施一侧感兴趣?事件流与可观测性管道文档介绍了 Datadog 和 Galileo 如何追踪模型调用。

技术作家的角色是在扩大,而不是在缩小。总得有人维护这些系统检索的知识库。总得有人写系统提示,界定它们如何回应、在哪里停下。总得有人测试回答是否与文档一致。这些都是写作工作,都需要对人们如何获取信息的判断力。

技术作家应该了解大语言模型和 RAG 系统的基本原理。我们不必变成机器学习工程师,但应该参与AI产品的讨论。我们需要足够的管道知识,知道自己专长在哪里适用、在哪里不适用。

技术作家本来就在为多类读者写作。他们组织内容结构,划定范围,预判误用。这些技能可以直接用在AI工作上。

AI不会取代技术作家。模型每年的文字生成能力都在提高,但总得有人决定说什么、对谁说、在什么限度内说。

他们需要编辑。我们就是编辑。

你也可以自己写初稿,让AI代理充当校对和风格检查。

怎么在工作流里用AI,和用其他任何工具一样,由你自己决定。

工作在变,工具在变。工作本身不会消失。裁掉技术作家的团队,最后还是会把他们请回来。

阅读案例研究​

如果本文给了你"为什么重要"和"怎么运作",请读案例研究。它讲的是Artie背后的具体设计决策:

  • 读者分流
  • 知识落地
  • 人设校准
  • 安全防护栏
  • 生产部署时我会重新考虑的那些取舍

两篇各自独立。从你更感兴趣的那篇读起。