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

带截图的文档集很容易开始，但很难长期维护。每张图片记录的都是某一天的界面，而界面一直在变化。在采集前完成规划，决定了文档集能否撑过第一次界面改版。

本文介绍如何组织文档集、制定截图规则，以及在 Mac 上使用 Temposhot 制作截图。全文各节都以同一个示例展开：一个包含五个产品区域的小型开票 Web 应用，由一名同时负责客户支持的技术文档撰写人员维护。

整理读者需要解答的问题

在决定页面之前，先收集真实的问题。常见来源包括支持工单、销售通话、入职培训、内部聊天记录，以及当前文档上的搜索词。

用读者的措辞写下每个问题：

• “如何邀请团队成员？”
• “为什么导出的文件是空白的？”
• “Sync status 是什么意思？”
• “哪个套餐包含审计日志？”

合并重复的问题。合并后的列表即为文档集的范围，不在列表中的内容可以之后再处理。

示例：从工单到问题列表

开票团队导出了过去 90 天内的 240 份支持工单。仅阅读工单主题和客户的第一条消息就花了约两个小时。合并重复项后，剩下 52 个不同的问题。

其中 9 个问题各出现超过 10 次。这 9 个问题覆盖了将近一半的工单，因此决定了工作顺序。其余 43 个问题按区域整理进待办列表，区域包括发票、客户、付款、设置和账单。

记录读者使用的措辞

每个问题旁边都保留读者的原始措辞，即使它与界面标签不一致。写下“移除一张卡”的客户不会去搜索“付款方式”。页面标题应使用产品标签，而第一句可以重复读者的用词，使搜索能同时匹配两者。

同时记录每个问题的上下文，包括套餐、角色和设备。账户所有者提出的“如何退款一张发票”与查看者角色提出的同一问题，对应的页面不同。前者是任务指南，后者是关于权限不足的排障页面。

移除文档无法解决的问题

部分工单描述的是缺陷或缺失的功能。解释缺陷的页面会变成一个在修复后仍然保留的变通方案。示例中，合并过程中有 6 份缺陷报告被单独移出，未计入 52 个问题，并转交产品团队，而不是放入文档待办列表。

另一类问题来自令人困惑的标签。如果有 10 位读者询问 “Sync” 是什么意思，参考页面会有帮助，但更清晰的标签帮助更大。这类问题同样转交产品团队。只有在标签保持不变的情况下，才编写对应的页面。

为每个问题分配一种页面类型

不同的问题需要不同的页面结构。混在一起会导致页面冗长、难以浏览。

页面类型	回答的问题	截图
任务指南	“如何完成 X”	每个步骤一张
参考	“X 是什么意思”	每个界面一张带标注的概览图
排障	“X 为什么失败”	错误状态和解决方法
概念	“X 如何工作”	示意图，截图很少或没有

为列表中的每个问题标注类型。大多数产品问题最终会成为任务指南。

撰写前先统计截图数量

页面类型决定了页面会包含多少张图片。将其乘以页面数量，就是每次改版后需要更新的图片数量。在打开任何采集工具之前，先算出这个数字。

示例中，52 个问题里有 31 个成为任务指南，平均每个 7 个步骤。12 个成为排障页面，每页 2 张图片。6 个成为参考页面，每页 1 张带标注的概览图。3 个成为概念页面，不含截图。

247 张图片是这套文档的实际维护负担。若一个产品区域的改版涉及其中约五分之一，就需要替换约 50 张图片，大约需要一到两天的工作量。了解这个数字，有助于说明下文截图规范的合理性。

拆分混合多种类型的问题

有些问题同时属于两种类型。“为什么导出的文件是空白的，如何解决”是一个排障页面，同时链接到任务指南。排障页面写明错误和原因，完整的操作步骤则链接到任务指南。

制定截图规范

提前决定截图的呈现方式，并将其书面记录下来。统一的截图风格让文档看起来持续维护，也能加快更新速度。

• 窗口尺寸： 所有截图使用同一种固定尺寸。Action Capture 中的 Specific Window 目标可以在整次运行中保持同一窗口。
• 主题与语言： 使用浅色或深色，并且只使用一种界面语言。
• 数据： 仅使用示例账户和占位名称。
• 裁剪： 只保留窗口或面板，不截取整个桌面。使用 Framing，并将 Focus on action 设为 Balanced 或 Close。
• 标记： 每张图片只使用一个点击标记或箭头，并且只使用一种强调色。
• 格式： 界面文字使用 PNG；如果站点需要更小的文件，则使用 WebP。

同时明确哪些情况不需要截图，例如只有单个字段的设置、文字已经说明了标签的步骤，以及每次发布都会变化的界面。

将规范转化为采集设置

书面规范只有在采集设置与之相符时才有效。在 Action Capture 中配置一次，设置会保存在 Mac 上，供之后的每次运行使用。示例团队对全部 31 个任务指南使用了下表中的设置。

Specific Window 将一个浏览器窗口设为整次运行的采集目标，因此每个步骤的像素宽度相同。关闭 Include toolbar in captures，否则浮动工具栏会出现在文档图片中。除非任务涉及第二个窗口（例如密码管理器），否则保持 Capture outside clicks 关闭。

按页面类型设置取景级别

取景不会改变原始图片，因此规范可以指定一个级别，同时允许例外情况。任务指南默认使用 Balanced（级别 3），这样能保留足够的页面内容，方便读者找到控件。长设置列表中的小开关等小型控件则改用 Close（级别 4）。

参考概览图不使用取景。它们显示完整窗口并带有编号标签，因为其目的是标明每个区域。Step Numbers 是 Pro 功能，因此在免费版中，需要手动放置 Text 标签以达到相同效果。

判断何时不需要截图

每张图片都意味着未来的一次更新，因此规范还应列出无需截图的情况。示例团队跳过了只需在带标签字段中输入数值的步骤的截图。他们也跳过了 3 秒后消失的确认提示，改用文字描述该消息。

若以上五项都不适用，则只用文字描述该步骤。示例中，这条规则在采集开始前就从计划的 217 张任务指南图片中减少了 38 张。

为每次采集准备同一个示例账户

来自不同账户的截图会显示不同的名称、金额和日期，读者会注意到这些差异。示例团队创建了一个示例工作区，包含 3 位客户、12 张发票和 2 种付款方式，全部使用占位名称。每个指南都从同一个工作区开始，因此每个页面上的客户名称都一致。

每次运行前重置示例数据。如果某个指南是在另一个指南删除了一张发票之后录制的，它会显示 11 张发票而不是 12 张，下次更新时就无法对应。在规范文档的开头写明重置步骤，方便其他撰写人员重复操作。

每次运行前把浏览器窗口设为固定尺寸，并保持不变。Temposhot 按窗口当前尺寸采集，不会调整窗口大小。在规范中记录类似“浏览器窗口宽 1440 点，缩放 100%”的说明，可以保证不同日期的截图比例一致。

命名并存放图片以便替换

每张图片迟早都会被替换。文件命名应便于快速找到同一界面的全部图片。

采用 area-task-step.png 这样的命名方式，例如 billing-change-plan-03.png，文件会按区域和任务排序。每个指南使用一个文件夹，并保存该指南对应的 Temposhot Document，以便编辑后重新导出。

Temposhot 导出图片时会使用页面标题作为文件名。应在导出前设置标题，或导出后在文档仓库中重命名文件。ZIP 包会在渲染的 PNG 页面旁添加 document.json，如果需要通过脚本将文件导入文档系统，这一点会有帮助。

示例文档集的文件夹结构

每个产品区域一个文件夹，区域文件夹下每个指南一个文件夹。导出的图片与使用它们的页面放在同一位置，因此修改指南的拉取请求也会显示哪些图片发生了变化。

保持页面标题与文件名同步

Temposhot 会以页面标题命名图片文件，因此类似 Click "Change plan" 的标题会生成难以排序的文件名。有两种可行的做法：将页面标题改写为最终面向读者的文本，然后用脚本在仓库中重命名文件；或者导出 ZIP 包，并根据 document.json 中的页面顺序命名文件。

无论团队选择哪种做法，文件名中的步骤编号都应与页面上的步骤编号一致。删除第 4 步后，应在同一次提交中为之后的文件重新编号。

保存源 Documents

每张导出的图片都来自记录它的那台 Mac 上的 Document。Documents 存放在该 Mac 的 Documents 库中（Command+4），Temposhot 不会同步它们。将每个 Document 命名为与指南文件夹完全相同的名称，例如 billing-change-plan，这样就能通过在库中搜索找到任何图片的来源。

先写任务指南，再写概览导览

任务指南回答最常见的问题，也最容易验证。应优先编写。

1. 打开 Action Capture

   按 Command+3，选择 Start Action Capture，然后选择 Specific Window。

2. 执行任务

   完整操作一次任务。每次被接受的点击都会保存点击前的窗口画面，并通过 Parse clicked elements 生成草稿标题。

3. 完成并编辑

   选择 Finish capture。在编辑器中改写标题、设置取景并添加标记。

4. 导出页面

   打开 More export formats，选择 PNG 或 WebP 页面，用于文档站点。

产品导览和概览页面留到之后再做，等任务指南确定了哪些界面最重要。Action Capture 指南和Documents 导出指南介绍了更多细节。

按工单量安排第一批内容

示例团队在第一周采集了最常被询问的 9 个问题。每个指南耗时约 25 分钟：重置示例账户 5 分钟，录制 5 分钟，编辑标题、取景和标记 15 分钟。9 个指南总计约四小时。

将草稿标题改写为操作说明

Parse clicked elements 会根据控件名称填写页面标题，例如 Click "Change plan"。对于没有可读名称的控件，标题为 Click here。两者都只是草稿。面向读者的标题应以动词开头，用粗体标出控件名称，并在结果不明显时补充说明结果。

草稿标题	改写后的标题
Click "Billing"	在侧边栏中打开 Billing
Click here	选择 Team 的套餐卡片
Click "Confirm"	选择 Confirm，在下次续费时切换套餐

改写后的标题在导出时也会成为图片文件名，因此清晰的标题对读者和仓库都有帮助。

对照免费版的步骤上限进行检查

免费版的 Action Capture 运行在 5 个步骤后暂停，已采集的步骤仍会保留。示例中的七步指南需要 Temposhot Pro，或者在一个 Document 中添加两次运行。添加第二次运行可以通过 Pages 面板中的 Capture new images… 完成，它会把新画面追加到当前打开的 Document 中。

使用键盘快捷键编辑页面

大部分时间都花在编辑上，每个指南约 25 分钟。下表列出了文档页面编辑中最常用的快捷键。

标注是非破坏性的。本次版本中添加的矩形可以在下次改版后移动或删除，无需重新采集该步骤，前提是底层界面仍与之相符。

连接文档集

读者很少会直接进入所需的页面。应链接各个页面，使读者能从概念跳转到任务，或从错误跳转到解决方法。

• 每个任务指南链接到其前置任务和下一项可能的任务。
• 每个排障页面链接到修复该问题的任务指南。
• 每个参考页面链接到使用该界面的任务。

每个产品区域放一个简短的索引页面，按目标列出任务，方便不习惯搜索而喜欢浏览的读者。

从一个问题出发的链接结构

示例中的“为什么导出的文件是空白的”问题生成了一条由四个页面组成的链路。读者进入其中任一页面后，都能一步到达其他三个页面。

避免孤立页面

发布后，列出所有页面并统计入站链接数。没有入站链接的页面只能通过搜索找到。示例中，52 个页面里有 4 个没有入站链接，已全部添加到所属区域的索引页面中。

分配负责人与审核触发条件

每个页面都应有负责人，通常是负责该功能的团队。同时记录截图对应的产品版本。

除日历提醒外，以下审核触发条件更有效：

• 某次发布改变了文档集中展示的界面。
• 某个标签或菜单项被重命名。
• 支持团队报告某个步骤与实际界面不符。
• 经过固定周期（例如一个季度），且没有其他触发条件。

关于更新流程，请参阅保持截图文档最新。

发布后替换图片

发布改变了某个界面时，文件名可以快速定位受影响的图片。在仓库中搜索区域前缀，打开同名的 Documents，并仅重新运行发生变化的步骤。

新采集的页面可以插入到所选页面之后。选择变化步骤之前的页面，再运行采集，新页面就会出现在正确的位置。

按产品区域划分负责人

一名撰写人员无法在每次发布后审核 52 个页面。示例团队将每个区域分配给负责该区域的工程师，由撰写人员担任编辑。负责人在发布工单中标记发生变化的界面，撰写人员负责替换图片。

在每个页面记录产品版本

在页面元数据或页面末行添加产品版本，例如“截图对应版本 4.2”。支持团队报告不一致时，版本号可以告诉负责人页面落后了多少。落后两个以上版本的页面会排在审核队列的最前面。

常见问题

软件文档页面应有多少张截图？

任务指南每个步骤一张，其他页面尽量少放。每张图片都意味着未来的一次更新，因此只在能减轻读者负担时才添加。

文档截图应显示完整屏幕吗？

很少需要。应裁剪到窗口或面板。全屏截图会显示无关的应用，并使界面文字变小。

什么是视觉化文档？

指将截图、示意图或视频与文字配合使用的文档。详见术语表中的视觉化文档。

文档站点应使用哪种图片格式？

PNG 能保持界面文字清晰。WebP 文件更小，但只有当 Mac 上安装了 WebP 编码器时，才会在 More export formats 中显示。导出 PNG 后，还可以使用 Image Compressor 进一步压缩文件，再上传。

改版后更新截图需要多长时间？

取决于有多少图片展示了发生变化的界面。示例中，一个区域的改版涉及约 247 张图片中的 50 张。仅重新运行已保存的 Document 中发生变化的步骤，耗时一到两天；如果从零重建同样的指南，则需要约一周。

多名撰写人员能否共享同一个 Temposhot Document？

不能。Document 保存在创建它的 Mac 上。应通过文档仓库共享导出的文件，并将每个指南的源 Document 保留在其负责人的 Mac 上。

将点击操作整理为清晰的分步指南

Action Capture 可以在一次操作中录制每个任务指南，并保持窗口尺寸一致、生成草稿标题。下载 Temposhot，从你列表中最常被询问的问题开始。