如何撰写真正有人会用的帮助中心文章

作者: Fraser Hardy

一个帮助中心页面,包含搜索栏、以任务命名的文章标题、编号步骤和嵌入的产品截图

有人在您的帮助中心搜索框里输入“导出发票”,得到三条结果:“账单概览”“报表”和“数据入门”。没有一条提到导出。他们关掉标签页,给您发了邮件。

这就是大多数帮助中心文章的问题:它们是按产品的构造方式组织的,而不是按人们想做的事情组织的。

所以先给出简短的答案。要写出真正有人会用的帮助中心文章:用客户的话,以单个任务来命名每一篇文章;用一句话说明它的作用;列出需要提前准备的东西;给出编号步骤,每步只做一个操作;在人们容易迷路的地方加一张截图;最后说明成功后他们应该看到什么。一篇文章,一个任务。如果您发现自己在写“您还可以”,那很可能是第二篇文章。

本文其余的部分是细节:一份可以复制的模板、一次改写前后的对比、先写什么,以及如何避免这一切在上线六周后就过时。

什么样的知识库文章才算好?

没人会为了好玩去读帮助文档。人们是在做事的途中、带着些许烦躁来到这里的,通常来自搜索(您的搜索或 Google 的搜索),或者来自您团队成员粘贴在回复里的链接。他们是在快速浏览。他们想找到第 3 步,做完,然后离开。

所以,一篇好的知识库文章,应当让一个在快速浏览、略带烦躁的人,不用重复阅读任何内容就能完成任务。实际做法是:

Diátaxis 框架把文档分为教程、操作指南、参考和说明。大多数帮助中心文章应当是操作指南。常见的错误是把四种类型混在同一个页面上,结果想找第 4 步的人,得先读完三段关于这个功能为什么存在的文字。

一份可以直接套用的帮助中心文章模板

帮助中心文章的结构图解:任务标题、简短引言、“开始之前”框、编号步骤、截图、后续情况和故障排查部分

这是我写每一篇任务型文章时都会从它开始的模板。它适用于 Zendesk、Intercom、Help Scout、GitBook,或者您代码仓库里的一个 Markdown 文件夹。

# [Verb] [the thing]
<!-- e.g. "Export your invoices to CSV" -->

[One or two sentences: what this does and when you'd want it.
Mention the plan or role if it's restricted.]

**Before you start**
- You need [role or permission], e.g. Admin or Owner
- [Anything to have ready: a file, an API key, a connected account]

## Steps

1. Go to **[Page name]** in the left sidebar.
2. Click **[Exact button label]**.
3. In **[Field name]**, enter [what, with an example value].
4. Click **[Confirm button label]**.

<!-- Screenshot of the step where people get stuck.
     Crop to the relevant area, highlight the target. -->

## What happens next

[What they'll see when it worked. How long it takes.
Who gets notified.]

## If it didn't work

- **[Symptom in the customer's words]**: [cause and fix]
- **[Second most common symptom]**: [cause and fix]

## Related

- [The task people usually do next]
- [The reverse task, e.g. "Remove a teammate"]

使用时有几点说明。

引言不是推销。“我们强大的导出功能让您完全掌控自己的数据”,对读者来说什么信息也没有。“把某个日期范围内的所有发票下载为 CSV 文件,可以用 Excel 或 Google 表格打开”,才能让读者知道自己有没有找对页面。

“开始之前”能避免最多的工单。 典型的失败是:有人照着做了六步,到第七步才发现只有管理员才能操作。把权限和套餐限制放在最前面,而不是放在末尾的一条备注里。

“如果没有成功”应当来自真实的工单。 不要凭空编造排障内容。翻一翻上个月的客服邮件,记下人们真正卡在哪里。两三条就足够了。如果您想要一种可重复的方法,我们另外写了一篇指南,讲如何把支持工单变成帮助文章。

改写前后对比:重写一篇典型的帮助文章

改写前后的对比:一篇以功能命名、满是大段文字的文章,被改写成以任务命名、带有编号步骤和明确结果的文章

下面是一个功能上线那一周往往会写出来的文章。产品是虚构的,但这种模式不是。

团队管理

我们的团队管理功能让协作变得轻松。在设置区域,您可以管理您的团队,包括通过“成员”选项卡添加新成员(您会在那里找到“添加成员”按钮),以及选择管理员、编辑者或查看者等角色,这些角色决定了每个人可以访问的内容。受邀用户会收到一封电子邮件。请注意,只有管理员可以添加成员,而席位数量取决于您的套餐。

读者需要的一切都在里面了。但顺序不对,标题是没人会搜索的,而权限方面的限制放在了最后一句。

下面是改写后的版本:

邀请队友

把某个人添加到您的工作区,让他们可以查看和编辑项目。

开始之前: 您需要是管理员。每个人会占用您套餐中的一个席位。您可以在设置 > 账单中查看还剩多少个席位。

  1. 前往设置 > 成员。
  2. 点击添加成员。
  3. 输入对方的电子邮件地址。
  4. 选择一个角色:管理员、编辑者或查看者。
  5. 点击发送邀请。

接下来会发生什么: 对方会收到一封邮件邀请。在接受之前,他们会在成员列表中显示,并带有待处理标记。

如果没有成功: 如果添加成员显示为灰色,说明您的席位已经用完。请移除某个人,或在设置 > 账单中增加席位。

事实相同,篇幅也差不多。但标题与人们输入的搜索词吻合,限制条件放在前面,每一步只有一个操作,读者也知道什么时候算完成。各个角色的说明被移到了单独的一篇短文章里(“各个角色能做什么”),并从第 4 步链接过去。

一篇帮助中心文章应该多长?

任务需要多长就多长,不要更长。作为经验法则,单任务的操作指南大约在 150 到 500 个词之间。如果远远超出这个范围,就检查一下是不是把两个任务粘在了一起,或者跑偏去解释这个功能背后的理念了。

例外是安装设置类指南,比如“连接您的 Shopify 店铺”,这类内容确实有十几步,还横跨两个系统。这类文章可以很长,只要把它们拆成读者可以直接跳转的 H2 小节就行。

截图在哪里有帮助,又在哪里有害

截图是读者最先注意到的东西,也是团队最少维护的东西。

在界面含糊的地方使用截图:拥挤的设置页面、带有六个字段的弹窗、位置出乎意料的按钮。对于“点击保存”这种就不必了。紧凑地裁剪到关键区域,如果画面很杂乱,就把目标高亮出来。

问题在于,每张截图都是在承诺界面仍然是那个样子。挪动一个菜单,就会有几十篇文章悄悄地向客户展示一个已经不存在的页面。这正是主张自动化截图、而不是手动截图的主要理由。我们在如何自动创建产品截图中比较了各种方案(Playwright 脚本、屏幕录制工具、替您捕获截图的工具)。

一篇已发布的帮助中心文章,带有任务标题、一行引言,以及读者正在看的那个页面的嵌入截图

先写什么

如果您是从零开始,不要试图把每个功能都记录下来。按这个顺序写:

  1. 最初的十五分钟。 注册、第一个设置步骤、第一个“哦,这个有用”的时刻。每个新用户都会读这些。
  2. 您最常见的支持问题。 翻一翻您的收件箱。这个月您回答过三次的问题,都应该有一篇文章。
  3. 任何涉及金钱或数据的内容。 账单变更、取消、删除、导出。人们在这些地方会紧张,需要的是确定性,而不是含糊其辞的一段话。
  4. 集成。 连接第三方账户时,人们常常卡在您无法控制的页面上。
  5. 其他所有内容,大致按人们遇到的频率排序。

把它们归入几个按客户思维方式命名的集合:“入门”“账单与账户”“使用[您的核心功能]”“集成”“故障排查”。避免使用照搬内部团队结构的集合。

一个帮助中心内容树,分为“入门”和“改进回复”等集合,每个集合下是以任务命名的简短文章

撰写帮助文档:积少成多的小习惯

Google 开发者文档风格指南面向的是技术文档,但其中关于清晰度和语气的大部分建议,同样适用于面向客户的帮助文档。

没人规划过的部分:让文章保持准确

写文章是容易的部分。难的是,您的产品每周都在变,而您的帮助中心却不会。

无论使用什么工具,以下几点都有帮助:

我们在如何让文档保持最新中认真地讲了这个问题,包括如何把文档审阅与您的发布流程结合起来。如果您会发布发布说明,同样的原则也适用:请看如何写出客户真正会读的更新日志。

Ellie Docs 的定位

声明一下:我们开发了一款做这件事的工具。Ellie Docs 连接到您的 GitHub 代码仓库,读取代码来弄清楚您的功能和面向用户的页面,并起草一个完整的帮助中心。它在沙盒中运行您的应用,捕获已登录产品的真实截图,并放进文章里。

Ellie Docs 文章编辑器,显示一篇起草好的帮助文章,带有自动捕获的产品截图,以及该文章所依据的功能

我最看重的部分是维护。当某个 PR 合并时,Ellie 会检查这次变更影响了哪些文章,并以差异对比的形式提出修改,由您接受或忽略。没有任何内容会自动发布,读者看到什么仍然由您决定,只是您不必再通过一张支持工单,才发现第 6 步已经错了一个月。

如果您已经有帮助中心,它会把您现有的文章导入为草稿,这样您就不必从头开始。有免费方案,无需绑定银行卡。

如果您更愿意全部手动完成,上面的模板单独使用也完全没问题。

人们常问的几个问题

帮助中心和知识库有什么区别? 实际上区别不大。“知识库”通常指文章的集合,而“帮助中心”指在其之上带有搜索和导航的、面向客户的网站。大多数工具对这两个术语不加区分。

谁应该写帮助文章:客服、产品还是工程? 谁最接近问题,谁来写。客服知道什么让人困惑,工程知道改了什么。一个行之有效的做法是由客服负责帮助中心,工程师在他们的 PR 里标记受影响的文章。

想要一份从您自己的代码库生成的帮助中心初稿吗?免费试用 Ellie Docs,看看它能从您的代码仓库里产出什么。