图像、图表、截图和视频指南
在 Grafana Labs，媒体是内容有用、清晰和简洁的重要组成部分。在为文档创建图像时，请遵循本节中的标准。
图像和图表指南
图像和图表可以补充文本，使读者能够快速理解概念并以简化的方式可视化复杂流程。但是，由于翻译服务和视障工具无法很好地解释或翻译图像，因此请避免使用图像来替代文本。
何时使用图像和图表
在以下情况下，请考虑使用图像或图表：
- 澄清配置和设置，例如虚拟服务器的架构
- 定义 Grafana 产品中的复杂工作流程
请勿在以下情况下包含图像或图表：
- 工作流程过于简单
- 没有与 Grafana 产品的交互
图像和图表标准
请遵循以下图像和图表标准：
大小：为了减少页面加载时间，请在不影响可用性的前提下，使图像和图表尽可能小。
除非图像清晰度对于理解至关重要，否则在保存图像时请使用 65-75% 的质量。调整图像大小时请遵循以下建议：
- 水平方向：最大宽度 1200px
- 垂直方向：最大高度 900px
范围：将图像内容限制在相关部分。
不要包含分散注意力或不必要的内容和空白，或者您的浏览器窗口、浏览器标签页或其他窗口装饰。
格式：PNG 和 SVG 是首选图像格式。
仅对照片使用 JPG 格式。
版权：您必须确定图像或图表是否受版权保护。
如果是，您必须获得许可并注明出处。
文件名：请遵循媒体资产文件命名约定中记录的命名约定。
浅色模式/深色模式：如果您要添加图像的页面为白色或浅色，请使用深色模式的图像。如果页面为黑色或深色，请使用浅色模式的图像。这可以确保足够的对比度。
个人身份信息 (PII)
务必遮盖、修改或删除任何 PII，例如密码、登录信息、账户详细信息或其他可能危及安全的信息。
替代文本和图注
确保为每张图片包含替代文本。图注是可选的。
图表资产
要创建图表，您需要访问推荐的软件并下载所需的图标和模板。
向创意/Web 团队请求图表
Grafana Labs 的创意/Web 团队为 Grafana Labs 内部贡献者开发的图表提供支持。如果您是 Grafana Labs 员工，可以在 #design Slack 频道联系他们。如果您不是 Grafana Labs 员工，请创建议题来提出您的请求。
截图指南
在编写用户界面文档时，请考虑是否需要包含截图。仅凭文字无法充分传达说明时，截图会很有帮助。
用户也喜欢截图并认为它们很有用。但是，截图难以维护且耗时，并且可能带来翻译问题。
因此，您应尽量减少在内容中使用截图。
何时使用截图
在以下情况下，请考虑使用截图：
- 提供可视化的示例
- 显示使用查询和设置填充的面板
- 在复杂或冗长的流程中为用户提供方向
- 显示下拉菜单之间的复杂关系，例如包含信息多个子集和许多可选项的菜单
- 强调用户界面中的某个功能或变化
何时不使用截图
请勿对以下项使用截图：
- 简单的创建操作，例如创建用户、团队、组织等
- 主要或次要导航项
- 代码示例（请改为在代码块中显示代码示例）
- 不复杂的对话框
- 消息文本（请改为在 Markdown 中显示消息文本）
- 进度条
- 简单的页面，例如向导页面和欢迎页面
- 在其他创作工具中创建的表格
- 可能频繁更改的页面
截图替代方案
仅在必要时向您的文档添加截图。您也可以考虑明确说明用户交互的用户界面元素。添加按钮、导航项、开关、菜单等名称，使其与用户界面上显示的一致。
例如，不要包含截图来 ilustrate 说明，例如“要添加仪表盘，请点击 仪表盘 > 新建仪表盘”。
任务中的截图
将截图放在其 ilustrate 的步骤下方。不要依赖截图来传达用户必须输入的信息或值。如果用户必须输入特定信息，请在步骤文本中提供该信息。但是，请确保截图准确反映步骤文本中的方向和值。
截图指南
创建截图时请参考以下指南：
- 大小：截图的最大宽度为 750 像素。理想情况下，截图的密度为 2:1，即 1500 像素。
- 分辨率：为获得最佳质量，请遵循以下指南：
- 在最高分辨率屏幕上截取截图。对于 Mac 用户来说，这通常是您的笔记本电脑屏幕。
- 非 Mac 用户：截图时请设置为最终最大宽度的两倍，以适应高分辨率屏幕。如果需要放大截图区域来满足此要求，请使用双指缩放以使像素大小加倍。（Mac 已按 2 倍 DPI 截取截图）。
- 在最高分辨率屏幕上审查截图，以准确了解其外观。在较低分辨率屏幕上，好的截图也可能看起来很糟糕。对于 Mac 用户来说，这通常是您的笔记本电脑屏幕。
- 范围：将截图范围限制在仅显示操作的用户界面部分，并包含足够的周边细节，以帮助用户找到该项目。
- 标注：要标注截图，请使用红色（十六进制颜色
FF0000）、箭头和方框。 - 文件名：请遵循媒体资产文件命名约定中记录的命名约定。
- 个人身份信息 (PII)：务必遮盖、修改或删除任何 PII，例如密码、登录信息、账户详细信息或其他可能危及安全的信息。
- 替代文本：确保为每张图片包含替代文本。
请参阅下一节查看优秀的截图示例。
截图示例
尺寸优秀的示例，图像限制在 600 像素宽
小范围示例
优秀的大范围示例，用户无需放大或在单独的标签页中打开图像即可看到所有所需信息：
优秀标注示例
视频指南
添加视频内容时请遵循以下指南：
仅使用来自 Grafana 官方来源的视频。
使用与主题相关且具体的视频。
为视频添加引言，说明读者可以从视频中看到什么。
这对于可访问性很重要，也可以避免读者观看与他们不相关的视频。
谨慎使用视频。
视频内容的更新比文本文档困难得多。
创意/Web 团队为博客文章和其他内容创建视频。他们将这些视频上传到 Vimeo 或 YouTube。
如果您需要面向外部项目的视频，可以使用他们的设计或视频请求表单进行申请。
Grafana YouTube 频道有一些不错的短视频，重点介绍了功能和特定主题。
您可以在页面中嵌入这些视频。要嵌入 YouTube 视频，请使用 youtube 短代码。要嵌入 Vimeo 视频，请使用 vimeo 短代码。
媒体资产文件命名约定
本节中的表格包含创建图像资产时应遵循的文件命名约定。
一般规则
- 文件名始终使用小写字母。
- 单词之间使用破折号；不要使用空格或下划线。
- 文件名中不要包含特殊字符或标点符号，产品版本号中的点号除外。例如：
grafana-9.2.release.png。 - 不要使用可能导致本地化问题的缩写。
- 例如，完整拼写
database，而不是使用db。 - 如有疑问，请不要使用缩写。
- 例如，完整拼写
| 资产类型 | 命名约定 |
|---|---|
| 截图 |
|
| 图标 |
尽可能具有描述性。例如，使用
|
| 徽标 |
命名 Grafana 徽标文件时，务必包含单词“Grafana”。 示例
|
| 照片 |
|
| 录制 |
|
推荐的图像编辑器
媒体资产存储位置
所有可视化资产都存储在 Google Cloud Storage 中，仅 Grafana Labs 员工可访问。您使用资产上传应用程序上传资产。下表列出了向 Grafana Labs 技术文档团队提供图像的步骤。
注意
通过资产上传应用程序上传的资产大小限制为 10MB。
对于较大的上传，请在 #website Slack 频道中联系我们讨论最佳方案。
| 如果您是 | 完成这些步骤 |
|---|---|
| Grafana Labs 员工 |
|
| Grafana Labs 社区贡献者 |
|
向 Markdown 文件添加图像
要向 Markdown 文件添加图像，请在相关步骤下方插入对图像的引用，并将其缩进，以便引用与步骤文本对齐。
图像引用路径遵循以下约定：
示例
在本地构建中测试图像
注意
本节适用于 Grafana Labs 内部贡献者。
生成文档的本地构建非常重要，这样您可以验证图像路径、图像大小和图像位置是否正确。
请遵循媒体资产存储位置中的步骤。
在您的分支上运行
make docs并验证图像是否出现。如果渲染效果不理想，请上传另一个版本并再次测试。
替代文本
替代文本是一个 HTML 属性，您可以使用它提供图像的简明描述。当图像不可见时（例如当人们使用屏幕阅读器或低带宽互联网连接时），会使用此文本。
在 Markdown 中，替代文本是在声明图像时方括号中的文本
或者，如果您使用 figure 短代码，可以使用 alt 参数
{{< figure alt="<ALT TEXT>" src="/media/<PATH TO IMAGE>" >}}您添加到 Grafana 文档中的每张图片都应该有替代文本。
HTML: The Living Standard 中关于编写优秀替代文本的一条很好的指导是：
思考替代文本的一种方式是：想象您在电话中向某人朗读包含图像的页面，而不提及存在图像。您用什么来代替图像进行描述，通常就是编写替代文本的良好起点。
有关如何编写优秀替代文本的更多信息，请参阅：
- Google 开发者文档风格指南
- HTML: The Living Standard
- gov.uk Design102 博客：替代方案是什么？如何编写优秀的替代文本
- W3C Web 可访问性倡议：替代文本决策树
屏幕录制
屏幕录制推荐的格式是 .mp4。不要使用 .gif 或 .mov 格式。特别要避免使用动画 GIF，因为它们会分散用户的注意力。有关分散注意力内容的更多信息，请参阅 理解成功标准 2.2.2：暂停、停止、隐藏 | WAI | W3C。
屏幕录制遵循与其他媒体资产相同的上传程序和文件命名约定。使用 video-embed 短代码在页面上嵌入视频
{{< video-embed src="/media/<path-to-recording/recording.mp4>" >}}