如何编写清楚的软件分步操作说明

清楚的软件图文文档会告诉读者该做什么、在哪里操作，以及怎样确认操作成功。先定义一个最终结果，再用准确界面标签写出直接动作，加入可见检查点，让文字配合实用截图，最后在不作口头解释的情况下测试整份指南。

**简要结论：**每一步都以动作开头，写明可见控件、必要数值或条件，并说明读者可以继续操作的结果。

定义一个最终结果

最终结果让每一步都有存在的理由。把任务写成读者可以完成并核验的结果，例如“将指南导出为 PNG 文件”或“为 Shotomatic 启用录屏权限”。

避免“学习编辑器”这类宽泛目标。它既不能告诉作者应包含哪些内容，也不能让读者知道什么时候已经完成。

每一步都从动作开始

第一句话应该直接告诉读者该做什么。以打开、选择、输入、拖动、审核或导出等动词开头。

比较以下两个版本：

修改前：“导出菜单位于右上角，包含多种实用格式。”

修改后：“打开右上角的 Export 菜单。”

修改后的版本让读者可以马上操作。只有在格式说明会影响选择时，才需要继续解释。

使用准确的界面标签

准确标签能帮助读者把说明与当前画面对应起来。保留界面中可见的大小写；菜单、按钮、字段、标签页和键盘快捷键的交互不同时，也要明确区分。

修改前：“进入设置区域，打开相关权限。”

修改后：“打开 System Settings > Privacy & Security > Screen & System Audio Recording，再启用 Shotomatic。”

不要使用读者在界面中看不到的内部产品名称。除非内容明确写给开发者或管理员，否则文档应以公开界面为准。

每一步只保留一个决策

一个步骤应只包含一个有意义的动作或决策。这样更容易找到失败位置，截图也更容易对应。

紧密相关的输入和确认可以放在一起：

在 Document title 中输入 Quarterly review，再选择 Save。

如果任一操作带有单独的警告、预期结果或分支，就应拆成两个步骤。

在重要操作后添加检查点

检查点告诉读者操作是否成功。权限更改、上传、导出、邀请、破坏性操作，以及任何可能需要等待的过渡之后，都应添加检查点。

修改前：“选择 Export PDF 并继续。”

修改后：“选择 Export PDF。保存对话框打开后，选择目标文件夹。”

有了检查点，应用仍停留在前一个界面时，读者就不会开始寻找文件夹。

根据可观察条件编写分支

分支应该从读者可以看到或确认的情况开始。先写正常路径，再把例外放在它所影响的步骤旁边。

修改前：“如有必要，调整权限。”

修改后：“如果窗口预览为空，请打开 System Settings > Privacy & Security > Screen & System Audio Recording，确认 Shotomatic 已启用。”

不要把所有罕见例外都塞进主指南。如果多个症状和原因会打断任务，请链接到专门的故障排查页面。

让截图显示位置和状态

文字和图片应该分工。文字说明动作、必要数值、条件和预期结果；截图显示控件位置和相关视觉状态。

不要用一个段落描述画面中的所有元素，也不要把整条说明作为大段文字叠在图片上。即使图片无法显示或难以看清，读者也应该能理解操作。

请参阅如何在 Mac 上为操作说明标注截图，选择点击标记、箭头、图形、文字、裁剪和模糊处理。

删除无用内容和隐含前提

无用内容会推迟动作，隐含前提则会让动作无法完成。删去“简单地”“只需”“像平时一样”和“根据需要配置”等说法，并用缺失的具体要求代替。

修改前：“只需根据需要配置导出选项。”

修改后：“选择 PNG，保留 Original size，再选择支持工单存放证据的文件夹。”

修改后的版本更长，是因为它包含读者需要的信息。简洁是删除无用词语，而不是删掉必要细节。

不要口头解释，直接测试说明

请选择一位没有参与撰写指南的读者进行测试。只提供写明的起始条件，请对方在没有口头纠正的情况下完成任务。

记录对方第一次犹豫、选错控件或遇到意外状态的位置。修改该处的说明或截图，再从头测试。

当读者能够得到写明的结果、每个分支都可以观察，而且步骤不依赖作者记忆时，指南才算完成。完整的点击采集流程请参阅如何在 Mac 上根据点击创建分步指南，并查看当前 Action Capture 工具。