如何在文档中使用图片、截图和视频
了解何时以及如何在文档中使用截图、GIF 和视频，包括格式选择、替代文本和长期维护方面的指导。
视觉媒体可以使复杂的工作流程比纯文本更加清晰——但它伴随着维护成本。你发布的每张截图都是在承诺当界面更改时对其进行更新。每个视频在其展示的流程发生变化时都会过时。
目标不是避免使用媒体，而是有意识地使用它，使其带来的清晰度超过维护它所需的工作量。
并非每个步骤都需要截图。并非每个概念都需要图表。在添加媒体之前，问问自己内容是否真的因为有了媒体而更清晰，还是简洁的文字和代码示例同样能满足用户的需求。
将截图用于难以用文字描述的任务——尤其是以界面为主的工作流程，用户需要在视觉上进行定位，或者不看到界面就无法确定正确的界面元素的情况。
避免在以下情况使用截图：
- 用户不容易误认的简单操作（“点击保存”）
- 频繁更改的内容——设置页面、仪表板和功能丰富的界面维护成本高
- 图片不提供信息的装饰性用途
GIF 适用于简短的循环演示——展示动画、展现多步骤交互，或捕捉一个比逐步描述更容易通过视觉跟随的工作流程。
保持 GIF 简短。超过几秒的文件会变得很大且加载缓慢，而且长 GIF 比用户可以暂停和倒退的短视频更难跟随。
将视频用于受益于解说的抽象概念，或者顺序和时间节奏很重要的长工作流程。对于复杂内容，视频比 GIF 更具无障碍性——用户可以暂停、倒退和控制播放速度。
将视频托管在 YouTube 或 Loom 等外部平台上并嵌入它们，而不是直接提供视频文件。视频文件会显著增加页面加载时间。
- 截图和图表使用 PNG。PNG 可以保持锐利的边缘和文字。
- 照片或文件大小很重要的图片使用 WebP。WebP 在质量相当的情况下比 PNG 和 JPEG 更小。
- 仅在需要动画时使用 GIF。对于静态图片，GIF 相比 PNG 没有优势。
- 在将图片添加到仓库之前先进行压缩。Squoosh 等工具可以在不产生可见质量损失的情况下减小文件大小。
- 保持截图为原始分辨率或缩小——永远不要放大，因为这会导致模糊。
- 文档的标准宽度通常为 800–1200px。更宽的截图会自动缩小，但在移动设备上可能显得很小。
- 将截图紧密裁剪到相关的界面区域。周围的浏览器边框、空白区域和无关元素会分散对你所展示内容的注意力。
每张图片都需要描述性的替代文本。替代文本使图片对屏幕阅读器用户无障碍可访问，并有助于 SEO。
编写描述图片内容以及其在上下文中重要性的替代文本：
<!-- 描述性且有上下文 -->
<!-- 没有用处 -->
参阅无障碍了解更多关于编写有效替代文本的信息。
使用描述性的 kebab-case 文件名来表明内容：
api-keys-settings.png ✓
screenshot-2024-01-15.png ✗
image1.png ✗描述性的文件名使查找和替换过时的图片更加容易，并对图片 SEO 有一定的贡献。
媒体是文档中维护成本最高的部分。一次界面重新设计就可能导致数十张截图同时过时。
以下几种做法可以减轻维护负担：
- 紧密裁剪到相关元素。 仅显示正在讨论的组件的截图比包含导航栏、标题和周围界面的全页截图过时得更慢。
- 避免为频繁更改的内容使用截图。 如果一个设置页面每个季度都有界面更改，请考虑描述性文字是否比截图更容易维护。
- 保留源文件。 尽可能存储未压缩的原始文件或分层文件，这样截图可以在不需要重新截取的情况下进行更新。
- 记录每张图片展示的内容。 在 MDX 中添加注释或在共享的图片清单中注明图片描述的内容，可以在审查期间更快地识别过时的资源。