如何规划一套基于截图的软件文档

如果每个团队都用不同方式组织软件页面，一套可视化文档很快就会难以维护。应从读者的问题出发，为每个答案指定页面类型，制定截图规范，先制作价值最高的指南，再把它们连接起来，并记录每页由谁复查。

简而言之： 围绕读者任务组织文档，不要照着产品菜单逐项介绍。每个问题只给一个明确答案，只有截图能减少不确定性时才使用，并记录界面变化后由谁更新每份指南。

列出读者需要解答的问题

文档清单应从读者的问题开始，而不是逐屏介绍产品。收集支持工单、入职培训、销售交接、版本反馈和产品分析中出现的任务与问题。

每一项都写成结果或判断：

• 安装应用并授予必要权限；
• 捕捉所选窗口；
• 把 Document 导出为图片文件；
• 修复缺少屏幕预览的问题；
• 选择 Action Capture 或 Auto Capture。

把表达不同但意思相同的内容归到一个问题下。这样能避免不同团队用不同标题发布多篇答案几乎相同的页面。

为每个问题指定一种页面类型

页面类型决定读者预期的结构。任务使用教程，完整选项使用参考页，症状和修复使用故障排查页，变更则写进发行说明。

读者问题	最合适的页面类型	主要内容
这项功能有什么用？	概览	用途、适用情况、限制、下一步
怎样完成这项任务？	教程	前置条件、有序步骤、结果
每个选项有什么作用？	参考页	完整字段、数值、默认值
为什么会失败？	故障排查	症状、原因检查、修复、证据
有哪些变化？	Changelog	已发布行为、迁移、可用范围

页面之间可以互相链接，但不应重复整份答案。概览页应把读者引向教程，而不是复制教程的所有步骤。

制定截图规范

截图规范能让可视化页面保持一致，也更容易维护。写清何时必须使用图片、允许出现哪些数据、怎样标记当前目标，以及源文件和编辑后文件存放在哪里。

以下情况适合使用截图：

• 定位控件或区域；
• 在可见选项中作选择；
• 展示操作前后的状态；
• 确认成功结果；
• 识别警告或错误。

准确命令、频繁变化的数值、概念说明，以及读者需要复制的信息，更适合用文字。与代码块相比，命令截图既不利于无障碍访问，也不方便使用。

为便于替换而命名和存储图片

稳定的文件名能让更新更安全。根据指南和步骤用途命名，不要按截图时的顺序命名。

例如，即使一段内容从第 2 步移到第 3 步，action-capture-start-session.webp 仍然准确。下一次编辑后，screenshot-02-final.webp 就可能产生误导。

把以下信息与指南放在一起，或记录在维护档案中：

• 源截图；
• 编辑并优化后的图片；
• 替代文本；
• 产品和操作系统版本；
• 截图日期；
• 页面负责人；
• 图片并非第一方素材时的来源或许可证。

先制作任务指南，再写宽泛介绍

任务指南应优先覆盖读者最常做的工作，或最耗费支持资源的错误。先记录设置、第一次成功输出、常见重复任务和代价较高的失败路径。

每份指南只对应一个完成结果。“所有导出相关内容”范围太广，既难遵循也难更新。可以把“把 Action Capture 页面导出为 PNG”单独成篇，再用一张参考表列出所有格式和方案要求。

执行任务时，Action Capture 可以收集点击驱动的步骤。捕捉、检查、编辑和导出流程见如何在 Mac 上根据点击制作分步指南。

连接整套文档

导航应跟随读者的下一个问题。设置指南可以链接到第一项任务，任务教程可以链接到常见失败的故障排查页，参考页则可以返回使用该选项的工作流。

链接文字应直接写明目的地。“授予屏幕录制权限”比“了解更多”更有用。相关链接保持精简，不要让它们取代文档层级。

测试时，只向读者提出问题，不告诉他们该打开哪一页。检查他们能否找到正确答案、完成任务，并从一个常见错误中恢复。

指定负责人和复查触发条件

每个可视化页面都需要负责人，以及触发复查的事件。定期复查有帮助，但界面、方案、权限变化或支持请求突然增加时，应提前检查。

记录以下字段：

页面负责人：
已验证的产品版本：
上次复查日期：
下次计划复查日期：
复查触发条件：
- UI 标签或布局变化
- 工作流或权限变化
- 方案或导出功能变化
- 支持问题反复出现

当读者能为每个重要问题找到一个明确答案，而且团队能判断产品变化会影响哪些页面，这套文档才算可用。点击驱动的可视化步骤可以使用 Action Capture，捕捉、编辑和导出流程见如何在 Mac 上根据点击制作分步指南。