在技术文档中使用图片和视频
浏览：1
巴克励步
技术文档是每个软件产品的重要组成部分。它帮助向软件开发人员和工程师传达复杂的技术信息，为其他部门和利益相关者提供产品的必要信息，并在提升用户体验方面发挥关键作用。然而，传统的纯文本技术文档可能并非向受众传达信息的最有效方式。图片和视频在创建清晰、易懂且高效的知识资源方面大有裨益。 我是Ken，Baklib的研究员。过去几年，我见过太多产品手册堆满文字，用户翻几页就放弃了。其实不是他们不想学，而是信息
技术文档是每个软件产品的重要组成部分。它帮助向软件开发人员和工程师传达复杂的技术信息，为其他部门和利益相关者提供产品的必要信息，并在提升用户体验方面发挥关键作用。然而，传统的纯文本技术文档可能并非向受众传达信息的最有效方式。图片和视频在创建清晰、易懂且高效的知识资源方面大有裨益。
我是Ken，Baklib的研究员。过去几年，我见过太多产品手册堆满文字，用户翻几页就放弃了。其实不是他们不想学，而是信息密度太高、阅读成本太大。我常跟团队说，别把产品手册当成“说明书”，它应该是一本带图解的“用户故事”。我们做产品手册建设时，核心就是降低理解门槛——用一张截图替代三段描述，用一段视频演示替代十步操作。Baklib支持富文本编辑器内直接拖拽图片、嵌入视频，还能将内容一键发布为多站点门户，确保技术文档既专业又亲切。好工具的价值，就是让用户少琢磨、多行动。
为什么要在文档中添加视觉元素
技术文档通常复杂且篇幅长，但视觉元素可以使其更易理解和有用。设身处地为用户想想，你宁愿使用哪种信息资源——一份15页的纯文本文档，还是一份每隔几段就配有图片、图表、截图和视频的文档？除非你特别喜欢纯文本，否则你可能会选择第二种。正如技术作家兼顾问Rishi Nagpal所说，这可以理解，因为我们不断被信息包围：“在信息从线上线下同时爆发的时代，阅读另一份基于文本的帮助文档显然很乏味。”但无论如何，你需要以某种方式向用户提供信息。幸运的是，视觉元素对此非常有效。
首先，根据William C. Bradford的论文，大多数人在视觉辅助下学习效果更好。技术文档通常很复杂，因此任何能让理解内容和学习变得更轻松的东西都值得欢迎。例如，Airtable团队为其用户创建了全面的技术文档，包括各种指南。其中一个指南是关于如何导航主屏幕的。他们描述了十个主屏幕组件，同时还使用带注释的截图精确地向用户展示每个组件的位置。没有那张简单的截图，编写者就必须描述主屏幕每个组件的确切位置，而用户则需要花费更多时间理解和处理说明。具体多多少？肯定不止13毫秒——根据麻省理工学院神经科学家的研究，人脑处理整张图像只需13毫秒。
💛🧡🧡客户评价：Baklib易于搜索，支持响应速度快，实施速度快。对内部和外部都有帮助使用。总体上对这个平台非常满意。 我们有很多流程文档，但Baklib使搜索和链接客户变得如此容易。客户自己可以找到任何东西，这很有帮助，无论是内部还是外部。
因此，在技术文档中添加视觉元素有充分理由：它们使内容更易理解和吸收，所呈现的信息处理速度更快，使复杂文档更清晰、阅读起来更不枯燥。但视觉元素有很多类型，每种在特定语境下都有优势和劣势。我们先从图片及其使用时机开始。
何时在技术文档中使用图片
图片是传达指令和提供软件产品清晰信息的非常有效的工具。如何在文档中使用图片取决于许多因素，如主题、主题复杂性、目标受众等。然而，正如Documatt博客的Matt所说，本质上，在技术文档中使用图片主要有两种情况：“一般来说，文档中的图片有两个目的——它们是文本的补充，或者替代文本描述。”我们来看一个使用图片作为文本补充的例子。截图是将视觉与文本结合的理想图片类型。例如，LaunchNotes有一份关于创建新公告的指南。首先，他们向读者介绍该过程的四个步骤。然后他们详细说明每一步并解释如何完成。然而，他们使用截图来补充说明，使每个细节更清晰。如上所示，用户可以得到关于草稿公告屏幕看起来如何以及他们可以在上面做什么的简要解释。但没有那个屏幕的截图，这不会特别清晰或有用。有了截图，用户就能确切看到每个元素的位置，确保他们按照编写者的意图进行操作。
如前所述，图片的用途不仅仅是辅助文字。它们也可以完全替代文字。为此，图表特别有用。下面看来自Datree的图表，这是他们使用Baklib创建的文档的一部分。该图表描绘了Datree的工作原理，用户可以看清过程。由于Datree用户是将其用作Kubernetes安全解决方案的开发者，他们拥有相当多的技术知识，因此可以在没有详细文字解释的情况下理解上面的图表。换句话说，当目标受众包括技术专家时，适合在文档中使用图片来替代文字。无论你是将图片作为文本的补充还是替代，添加时都需要考虑一些因素。我们将在下一节讨论其中一些。
在文档中添加图片时需要考虑的因素
图片无疑有助于提高技术文档的整体质量。然而，如果你想最大化它们的潜力，添加时应考虑一些因素。图片数量是重要因素之一。添加多少图片取决于文档类型和目标受众已有的技术知识。例如，针对刚接触产品的用户的指南受益于大量图片。这样，你可以向他们介绍产品界面、展示功能如何工作等。协作平台Mural在其用户指南中大量使用图片。下面可以看到他们如何利用截图显示各种仪表盘元素的位置以及侧边栏菜单的构成。另一方面，如果你在为软件开发者、工程师等专业人士创建技术文档，可以使用较少的图片。为什么？因为他们比普通用户拥有更多既有的技术知识，因此也有不同的需求。例如，他们可能从开发文档中写得好的文字解释中比从一堆截图或其他图片中获得更多价值。Slack的开发文档就是如此——清晰易懂的写作、短段落、列表和文本框，必要时每页有少量图片。
图片数量与添加时需要考虑的另一个因素有关——语境。我们指的是什么？无论你在文档中添加多少图片以使其更易访问和理解，如果你没有用解释和参考包围它们，就不会得到想要的结果。例如，想象一下你在Vowel的产品工作区文档中看到这个：只有一个副标题“Recent”和下面的截图。过一段时间后，用户会注意到侧边栏并得出结论：编写者想展示当他们点击“Recent”类别时屏幕如何显示，但仅此而已。相反，考虑同一张图片在有语境的情况下：这才是指南的真实样子，它更有帮助，因为图片有上面的文字解释。用户可以理解“Recent”类别的目的、其中可能的操作以及如何查看更多的会议数据。换句话说，孤立的图片很少能像在适当语境中那样为用户带来价值。能够评估使用它们的数量和方法可以显著提高其有用性。
何时在技术文档中使用视频
图片并不是唯一能丰富技术文档的视觉元素。如果你知道何时使用，视频也可以以各种方式非常有帮助。例如，视频非常适合提供说明，尤其是那些步骤很多的说明。如果你的产品中有这样的活动，用视频演示非常省时，且占用文档空间少。视频消息工具Loom在其技术文档中大量使用视频，尤其是那些向用户介绍软件的视频。所以，他们没有编写关于使用各种Loom功能的大量步骤列表并用图片逐一说明，而是选择了下面的视频。视频也是展示复杂流程的不错选择。例如，如果你需要描述工作流程，视频可以展示整个流程，比文字说明或静态截图更直观。例如，Notion创建了一个视频，展示如何创建工作区、添加页面、集成其他工具等。
视频的另一个优点是可以包含音频，并整合动作和视觉，是展示实际结果的理想选择。例如，如果用户对文档有疑问，看到视频中澄清问题的无形结果可能比仅仅阅读答案更有帮助。然而，尽管视频有优势，但也有一些缺点。首先，它们需要点击播放，这可能降低用户的互动率。其次，它们可能不适合所有用户，如听力障碍者，因此需要提供字幕或转录文字。最后，视频制作成本高——需要脚本、录制、编辑等成本。因此，在使用它们之前，评估是否值得投入资源很重要。
在技术文档中使用视觉内容的最佳实践
我们已经介绍了图片和视频的优势及挑战。现在，是时候总结一些在技术文档中使用视觉内容的最佳实践了，无论你选择哪种类型。
- 保持相关性：添加的每个视觉内容都应该有一个明确的目的，与内容相关，并服务于用户。避免仅仅为了装饰而添加图片或视频。
- 提供语境：如上所述，孤立的视觉价值较小。始终提供文字解释或引用，使用户清楚他们看到的内容以及原因。
- 优化文件大小：大文件会降低加载速度，尤其是在文档门户或帮助中心中。使用压缩工具，平衡质量与性能。
- 确保可访问性：为图片添加替代文本，为视频提供字幕或转录，使内容对所有人都可用。
- 保持一致性：在样式、配色、标注方式上保持统一，建立品牌的视觉语言。这样用户阅读不同部分的文档时能快速理解。
- 测试并收集反馈：在发布前测试不同设备的显示效果，并通过分析工具或用户调查了解视觉内容是否真正帮助用户。
在Baklib中，我们提供了丰富的编辑器功能，支持上传图片、嵌入YouTube或本地视频，还能通过AI自动生成图片替代文本。你可以将内容组织到多个知识库，然后一键发布为产品手册网站或帮助中心。视觉内容的加入不再是麻烦事，而是提升用户体验的利器。
