是否应该在文档中添加截图？
关于软件文档是否应包含截图，作者们在可用性与维护成本之间存在分歧。许多人认为，截图对于引导初学者通过复杂或杂乱的界面、支持视觉型学习者、澄清含糊文字，以及快速看出说明是否过时都非常有价值，尤其适用于教程和 UI 密集型工作流。另一些人则强调，截图可能不够无障碍、难以本地化且难以保持最新；它们应当补充而不是取代清晰、示例丰富的文本和扎实的参考材料，并最好通过自动化和测试来保持视觉内容与产品同步。
截图何时有帮助
- 普遍被认为对 GUI 密集、复杂或界面杂乱的 UI 很有价值（IDE、设计工具、云控制台、Azure/AWS 面板）。
- 对初学者、低频用户或非技术受众尤其有用，因为他们需要具体指导，并想知道“按钮 / 菜单 / 图标在哪里”。
- 帮助用户确认自己是否在正确的界面上，以及结果“看起来是否正确”。
- 在跨语言场景中也很有帮助，尤其是 UI 已本地化但教程未本地化时。
- 对营销 / README 页面也很适合，这样用户在安装前就能看到项目长什么样。
风险与缺点
- 主要问题是维护：UI 经常变化，截图会过时，而更新它们很费力。
- 如果图片缺少替代文本或文字等价内容，会有无障碍问题。
- 过度使用（每个微步骤都放截图）会让文档显得杂乱，并且会让读者一直停留在“入门级”。
- 终端会话和代码的截图受到强烈批评：无法复制/粘贴、难以更新、体积大且无障碍性差。
目标受众、学习风格与文档类型
- 受众、上下文和文档类型比任何一刀切的规则都更重要。
- 视觉型学习者和初学者受益很大；有经验的用户通常更喜欢简洁文本和参考材料。
- 有人强烈主张明确区分：参考文档、教程/学习指南、操作方法（how-to）和解释；截图最适合教程/操作方法，而不适合作为主要参考内容。
过时文档与版本管理
- 有人认为过时截图会削弱信任。
- 也有人反驳说，它们有用是因为能直观显示年代，并帮助用户推断哪些地方变了；而仅有错误文本则会悄无声息地误导。
- 有几条建议是：始终在截图上附上日期、版本或说明文字。
自动化与工具
- 多条评论主张通过测试框架（Playwright、Cypress、CI 流水线）自动生成截图，或者用实时 HTML/iframe 取代静态图片。
- 想法是：让测试和文档紧密集成，这样 UI 或 API 变更会导致测试失败，并迫使更新文档。
文本、示例与替代方案
- 强烈主张在截图旁边，或者取而代之，提供具体示例（API、CLI、配置）。
- 许多人不喜欢只有视频的文档；视频和导览可以作为补充，但不能替代可搜索、可快速浏览的文本。