如何为软件编写清晰的分步说明

清晰的软件说明能让读者无需思考说明本身就能完成任务。每个多余的词、模糊的标签或合并的步骤，都会让读者停下来重读。

本文介绍最关键的写作规则并附示例，以及在 Mac 上使用 Temposhot 制作指南时如何应用这些规则。

定义一个明确的完成结果

先写出结果，用一句读者可以核对的话表达：“发票已发送给客户，状态为 Sent。”这句话将成为标题和最后一步。

如果写不出一个结果，说明内容涵盖了多项任务，需要拆分。搜索“发送发票”的读者不希望先翻过“创建客户”的内容。

在放第一张截图之前写下结果。截图之后再写结果，往往会变成对录制过程的描述，把作者碰巧做过的每次点击都写进去。先写结果，才能决定哪些点击应该保留。仅用于在页面间跳转的点击，例如为了到达目标页面而打开的菜单，通常可以用一个指向目标位置的标签替代。

当一项任务涉及两种角色时，应分别写两份指南，每份只对应一个结果。负责审批发票的人和负责发送发票的人，起点与检查项各不相同。合并成一份指南，会让每位读者跳过与自己角色无关的部分。

可检查结果与模糊结果

当读者可以看着屏幕回答“是”或“否”时，结果才是可检查的。下表用两种写法展示同一项任务。

可检查的版本也决定了指南的长度。以可见状态结尾的指南有自然的最后一步，作者不需要再添加一段重复开头的结束语。

每一步以操作开头

读者会先扫视动词，所以把动词放在句首。

不佳	推荐
设置菜单现在应该已经打开。	打开 Settings。
接下来，你需要点击 Save。	选择 Save。
右上角有一个 Share 按钮。	在右上角选择 Share。
请确保已关闭通知。	关闭 Notifications。

保留一份简短的动词列表并始终统一使用：打开、选择、选取、输入、开启、关闭、拖动。对鼠标用户而言“点击”可以理解，但对键盘和触控用户并不适用，因此许多风格指南倾向使用“选择”。

步骤统一使用祈使句。“选择 Save”和“打开 Settings”直接告诉读者现在要做什么。“你应该选择 Save”多了一层读者需要先删掉才能行动的内容。步骤末尾的结果句同样如此，它描述屏幕显示的内容：“横幅显示 Changes saved。”

一种控件对应一个动词

动词列表只有在每个动词对应一类控件时才有效。读者看到“选取”会期待列表或菜单，看到“选择”则期待按钮或链接。下面的清单为每个动词给出一条规则。

当控件不符合列表中的任何动词时，描述它的位置和标签。打开选择器的控件使用“选取”，启动某个流程的控件使用“选择”。动词列表应保持简短，因为每增加一个动词，写作者就多记一条规则。

使用准确的界面标签

标签必须与界面显示完全一致，包括大小写和标点。如果按钮显示为 Add member，就不要写成“添加用户”。读者会按屏幕上的文字查找控件。

标签需要加粗，使其与句子其他部分区分开。只有在标签难以找到或在界面中出现多次时，才需要说明位置：“在工具栏中选择 Export，而不是在 File 菜单中。”

出现多次的标签

如果标签在两个地方出现，而步骤只写了标签名，读者可能会点错位置。对话框中常会重复出现工具栏按钮的文字，因此只写“选择 Export”会让人无法判断指的是哪个控件。解决办法是说明步骤指的是哪个位置，并写明读者接下来应看到的结果：“在工具栏中选择 Export。导出对话框打开。”第二句用于确认读者选中了正确的控件，然后再继续下一步。

菜单还会带来另一个问题。名为 Settings 的菜单项可能同时存在于应用菜单和窗口工具栏中。只有读者需要时才写出路径，并且只在首次使用该菜单的步骤中写一次。

读者查找标签时的规则

读者找不到某个标签时，通常会在屏幕上按准确文字搜索。改写的标签会把读者带到错误的位置，甚至找不到。下表展示了这些规则的应用方式。

标签在应用的不同版本间发生变化时，需要添加说明。在页面描述中写明版本号，例如“在版本 4 中，该按钮显示为 Invite。”这条说明能在读者提问之前解答疑问。

每个步骤只包含一个决定

每个步骤只包含一个操作或一次选择。“打开设置，选择账单，然后更改套餐”是三个步骤。读者回看屏幕时，如果句子很长，就会失去当前位置。

例外情况是在同一个小区域内、总是一起发生的两个操作，例如“输入验证码并选择 Verify”。即便如此，如果第二个操作带有条件，也应拆分。

决策步骤同样需要注意。当读者必须在多个选项之间做选择时，应在步骤中列出选项，或说明控制选择的设置项。“选择格式”让读者自行猜测有哪些选项。“在 Format 中选择 PDF 或 PNG。打印时选择 PDF”给出了可以直接应用的规则，读者无需再读一遍。

拆分复合步骤

复合步骤通常隐藏着一个决策点。下例从一个修改订阅的步骤开始，在读者需要确认的每个操作处进行拆分。

原句包含六个动词和一次确认。上面的四个步骤每步只有一个操作，最后一步包含一个检查点，下一节将介绍。

在重要操作之后添加检查点

在会改变内容的操作之后，告诉读者应该看到什么：“绿色横幅显示 Changes saved。”检查点能确认进度，并在读者继续执行五个步骤之前及早发现错误。

在保存、提交、导入、权限提示以及加载耗时较长的操作之后，都应添加检查点。

错误处理路径

检查点说明成功时的状态，错误处理路径说明失败时的状态以及下一步去哪里。每个可能失败的检查点都应配一条错误路径。路径需要写明界面上显示的消息、应执行的操作，以及需要返回的步骤。

以上传步骤为例。成功检查点写着：“文件名出现在列表中。”错误路径则写：“如果列表显示 Upload failed，选择 Try again。如果再次失败，请前往文件大小限制的故障排除页面。”读者能看到消息，知道该执行什么操作，也知道何时应停止。

错误路径应保持简短。包含三个分支的路径应放在单独的故障排除指南中，并从步骤中链接过去。如果一条路径需要多个屏幕才能说明，通常意味着它其实是两项任务。

长指南中检查点的位置

没有检查点的指南会在很晚的阶段才暴露问题，那时读者可能已经做了好几处需要撤销的更改。下面的数字来自一份 12 步的示例指南，检查点设置在读者的下一步操作依赖结果的位置。

显示明确结果的检查点比只写“完成”的检查点更有用。“完成”并不能确认屏幕上的任何状态。“该行显示 Imported，共 240 条记录”则给出了一个可与读者自己屏幕对照的数字。

基于可观察条件编写分支

分支最容易让读者迷失。分支应基于读者能看到的内容，而不是读者必须事先知道的内容。

• 不佳：“如果你使用的是旧版套餐，……”
• 推荐：“如果页面显示 Upgrade to continue，前往步骤 7。”

分支应保持简短。如果分支超过两个步骤，应将其移到单独的指南中，并添加链接。

避免依赖读者历史的分支。“如果你在 2025 年之前注册”要求读者记住屏幕上没有显示的信息。应改为屏幕上可见的结果：“如果账户页面显示 Legacy 标记，前往步骤 7。”基于屏幕的分支对新读者、回访读者，以及代替他人查阅指南的支持人员都适用。

从屏幕开始的分支

下面的流程展示了一个读者可以从屏幕上确认的分支。读者无需知道自己使用的是哪种套餐。

分支会将读者带回一个已知的位置。对于无法导出的读者，步骤 9 是指南的终点，其他读者则不需要跳过这一部分。

让截图展示位置和状态

文字说明要做什么，截图展示位置和外观。每个步骤使用一张截图，裁剪到相关区域，并在目标上做一个标记。截图还能确认状态：读者对照自己的屏幕，就知道是否走在正确的路线上。

Temposhot 会根据你的点击生成这种截图与文字的组合。打开 Action Capture（Command+3），在 Configure 下开启 Parse clicked elements，然后选择 Start Action Capture。每次有效点击都会保存点击前的屏幕，并生成类似 Click "[[element-name]]" 的草稿标题。点击 Finish capture 后，Document 会在编辑器中打开。

裁剪每张截图时，只保留步骤中提到的窗口或控件。全屏截图会显示许多控件，读者需要自己找出步骤指向的那一个。导出前，检查裁剪范围内是否包含隐私数据，例如账户名称或无关的通知，并以打印或显示时的实际尺寸检查图片。

按照上述规则改写每个草稿标题，例如将 Click "Save" 改为“选择 Save 以保存更改”。检查点和条件应写在 Page description 中。导出 PDF 时，描述可以显示在每张截图之前或之后（属于 Pro 自定义功能）。编辑器指南介绍了标题、描述和工具。

操作指南的设置

下列设置生成的每页对应一次点击，并且目标可见。它们适用于为单窗口读者编写的指南。

对于不依赖点击的屏幕，例如处理后才更新状态的界面，使用手动快捷键。这些步骤应开启 Show cursor in shortcut captures，使指针标出读者需要阅读的字段。

在整份指南中保持捕获目标一致。如果在指南中途从 Active Window 切换为 Specific Window，页面的取景方式会前后不一致。

编写步骤页面时的编辑器快捷键

大多数编辑都在编辑器中逐页完成。下列快捷键涵盖编写标题、描述和标记时最常用的操作。

删除冗余内容和隐含假设

删除不会改变读者操作的词语：

• “简单”、“只要”、“轻松”：这些词不提供信息，还会让遇到困难的读者感到更挫败。
• “你现在需要”、“请继续”：直接从动词开始。
• “如上所述”：重复事实，或链接到相关内容。

然后检查是否存在隐含假设。读者是否知道应用在哪里、应使用哪个账户、某个术语的含义？每个缺口添加一行说明，通常放在前提条件中。

统计删减量

冗余内容很容易添加，也很容易遗漏。编辑前后统计词数，能看出一轮修改删掉了多少内容。

删减的好处不止于缩短页面。每个被删掉的词语，都是读者停下来判断它是否重要的地方。修改后的步骤在第一次阅读时就能当作指令理解。

测试说明，但不解释

请没有做过该任务的人阅读说明，观察他们如何按步骤操作，并且不回答他们的问题。每次停顿或提问，都指向一个需要更清晰的动作、标签或检查点的步骤。

选择与读者相符的测试人员。亲自参与开发产品的人熟悉标签和流程，他们顺利完成的结果说明不了什么。来自支持团队，或担任目标角色的新员工，更容易发现作者已经习以为常、不再注意的问题。把指南和他们将要使用的账户交给测试人员，其他信息都不提供。

修改这些步骤，如果条件允许，换一位不同的人再次测试。两次顺利完成通常说明说明书可以正常使用。截图教程检查清单列出了发布前的其余检查项。

记录测试笔记

记录每次停顿的时间和步骤编号，原因留到测试结束后再整理。下面的时间线展示了一次九步指南的测试，得到了一项有用的发现。

笔记显示哪些步骤需要补充标签，哪些需要添加检查点。单次测试只能显示一种倾向，而不是比率。在修改指南之前，先进行第二次测试。

与操作指南一同保存的文件

操作指南包含的文件不止页面本身。源 Document 保存在 Documents 资料库中，导出的 PDF 和笔记则放在应用外的同一个文件夹中。该文件夹保留版本号和测试笔记，并与读者收到的文件放在一起，使下一次修改从同一份记录开始。

常见问题

说明中应使用“点击”还是“选择”？

“选择”适用于鼠标、键盘和触控。只有当读者主要使用鼠标，且风格指南偏好“点击”时，才使用“点击”。无论选用哪个词，都应统一使用。

每个步骤应该多长？

动作用一句话说明，结果或条件可以再加一句。较长的解释应放在备注或单独的页面中。

说明是否需要编号步骤？

当顺序重要时需要。编号让读者记住自己的位置，也方便支持人员引用“第 4 步”。Temposhot 的 PDF 导出可以添加步骤编号（Pro 功能）。

警告应放在哪里？

放在它所适用的步骤之前。破坏性操作之后再给出警告，读者看到时已经太晚了。

一份指南需要多少截图？

在屏幕发生变化或目标难以找到的每个步骤各需一张。只在已经可见的字段中输入文字的步骤不需要截图。初稿完成后对照步骤数量统计截图数，删除重复同一屏幕的截图。

发布后界面发生变化怎么办？

找出所有提到已变化标签或位置的步骤，同时更新截图和标题。标签已旧而截图已新，比只保留旧截图更容易让读者困惑。在页面描述或指南页脚中记录应用版本，让读者能判断指南对应的版本。

如何为仅使用键盘的读者编写说明？

当步骤依赖按键或焦点位置时，写明按键或焦点目标，例如“按 Tab 直到 Export 按钮获得焦点”。不要依赖“点击”一词，也不要依赖控件在屏幕上的位置，因为键盘用户无法以同样的方式看到位置。发布前仅用键盘完整测试一遍。

需要多少个检查点才够？

在每个保存、提交、导入或修改权限的操作之后各设一个，以及在任何耗时超过几秒的步骤之后设一个。检查点过多会拖慢读者，因此总是一起发生的两个操作的检查点可以合并。

将你的点击转化为清晰的分步指南

Action Capture 为每次点击生成一张截图和一个草稿标题，可直接套用上述写作规则。下载 Temposhot，在录制内容的基础上编写下一份指南。