文档

Writers' Toolkit

写作

风格指南

UX 写作

开源适用于开源版本的页面内容。

上次评审：2024 年 6 月 27 日

UX 写作

这些指南提供有关在构成 UI 的不同组件中创建文本、风格和语调的指导。它们帮助您构建增强用户体验、易于使用、一致且具有包容性的 UI。这些指南重点关注 UX 写作。有关 UI 元素的更多详细信息，请参阅 Grafana Storybook React 组件库。

编写 UI 文本的技巧

以下是编写清晰简洁的 UX 微文案的技巧。

使用友好且不过于正式的语调

使用对话式的语调，但不要像给朋友发短信那样随意。

像工程师之间轻松交谈一样与用户交流。
听起来像人类，并展现同理心。Grafana 项目是帮助人们完成工作和解决问题的工具。
避免在 UI 文本中使用“请”。

使用

我们将引导您完成创建 SLO 的过程。

避免使用

这里是 SLO 的设置指南。

清晰简洁

您使用的词越多，浪费的时间就越多。

只沟通必要的细节。
花时间编辑您的作品，让每个词都物有所值。

使用

保存更改

避免使用

您要保存更改吗？

用第二人称称呼用户

使用“您”或“您的”，仿佛 UI 正在与用户对话。但不要使用“请”。

使用

设置您的 SLO 目标。

避免使用

可以为 SLO 设置目标。

使用

详细信息请参阅Kubernetes 监控简介。

避免使用

有关详细信息，请参阅Kubernetes 监控简介。

使用主动语态

使用主动语态以明确谁在执行操作。

使用

服务器接收查询。

避免使用

查询由服务器接收。

在 UI 元素中使用句子大小写

只大写标题中的第一个词，冒号后子标题中的第一个词，以及任何专有名词（人、地点、产品）。

注意
如果您不确定某个事物是否是产品，请咨询产品经理；如果不存在产品经理，请咨询负责的小组。

使用

创建和管理仪表盘以可视化您的数据。

避免使用

创建和管理仪表盘以可视化您的数据。

使用

TLS/SSL 根证书

避免使用

TLS/SSL 根证书

其他公司的产品名称

在使用其他公司的产品名称或提及第三方产品名称时，始终遵循该品牌的命名和用法。

使用

Azure OpenAI Service

避免使用

Azure OpenAI 服务

避免使用为 UI 功能创建的词汇

尽可能避免使用 UI 术语。

使用

在您的 Grafana Cloud Stack 中，单击连接。

避免使用

在您的 Grafana Cloud Stack 中，单击连接按钮。

使用数字

大多数媒介中编写数字的准则是拼写出一到九的数字。在编写 UI 文本时，最好使用数字（1-9），因为它们更容易解析。

使用

您有 3 条消息。

避免使用

您有三条消息。

跳过不必要的标点

避免在 UI 元素中的单句后使用句号。

使用

按数据源搜索

避免使用

按数据源搜索。

不要在标签后使用冒号。

使用

按类型搜索

避免使用

按类型搜索

使用句号表示多句。

使用

指标、日志和链路追踪按摄取量计费。对于指标，我们根据该期间使用 95th 百分位数计算的活动序列数量进行计费。

避免使用

指标、日志和链路追踪按摄取量计费
对于指标，我们根据该期间使用 95th 百分位数计算的活动序列数量进行计费。

编写可扫描的描述性文本

使用冗长的描述性文本块会降低可读性。先写重要信息，使用简短的、带项目符号的列表。使用标题划分内容。

使用

开始之前，请确保您拥有以下项目
kubectl 命令行工具。要了解如何安装 kubectl，请参阅kubectl。
（可选）用于管理 Helm Chart 的 helm 命令行工具。要了解如何安装 helm，请参阅 Helm 文档中的安装 Helm。

避免使用

开始之前，请确保您的本地机器上安装了 kubectl 命令行工具。要了解如何安装 kubectl，请参阅 Kubernetes 文档中的kubectl。您可能还需要用于管理 Helm Chart 的 helm 命令行工具。要了解如何安装 helm，请参阅 Helm 文档中的安装 Helm。

为 UI 元素编写文本

以下部分提供了常见 UI 元素的写作指南

按钮
输入字段和验证
错误
警报模态框
确认模态框
工具提示
标题
链接

如果您希望 Grafana Labs 添加 UI 元素，请参阅本主题底部的模板。

按钮

当您希望用户执行操作时使用按钮，例如在现有系统中添加或创建新记录或信息类型。

按钮标签以动词开头。
目标是使用一到两个词，最多四个词。
使按钮标签具有描述性，并告诉用户单击它将执行什么操作。
与其使用确定或取消，不如具体说明。例如，使用保存 / 不保存，而不是保存 / 取消。
使用句子大小写，不带标点。例如，使用保存更改，而不是保存更改。

按钮的常见用例

按钮	何时使用	示例
创建	用于从头开始或在现有应用中创建新事物。创建可能涉及从头构建（通常是大型）事物。	创建创建事件创建条目
添加	用于在较大事物中添加小事物。向现有事物添加额外细节。添加通常是小型或单个步骤，工作量少于创建。	添加详情添加联系人
保存	将某物保存到服务器。	保存保存并退出保存更改
编辑	更改或更新已存在的事物。这不会影响服务器，直到用户保存。	编辑
预览	预览您正在处理内容的运行时版本。此操作不会将您带离或覆盖您已在的页面。	预览
取消	取消或离开某个过程。离开而不保存任何更改。尽管取消是常见的按钮名称，但最好具体说明正在取消的操作。	取消
关闭	关闭窗口。	关闭
删除	从服务器永久删除某物。这通常会弹出确认对话框，要求您确认决定。	删除通知策略删除此通知策略将永久将其移除。您确定要删除此策略吗？是的，删除
移除	从列表中移除项目。	移除

有关按钮的用法和示例，请参阅 Grafana Storybook React 组件库。

输入字段

输入字段标签应使用简短且可扫描的文本。使用句子大小写，并在字段标签前放置最清晰地描述用户需要在输入字段中输入值的术语。

如果您为输入字段提供说明，请清楚说明该字段的限制、要求和可用字符。必填字段使用红色星号标记。说明使用句子大小写，不带标点，除非有多句。

您可以选择在输入字段中提供描述性的占位符文本。如果这样做，请确保您的描述清晰简洁。占位符文本应暗示期望的值。

有关按钮的用法和示例，请参阅 Grafana Storybook React 组件库。

错误

使错误对用户可见、有帮助且易于理解。错误消息告诉用户发生了什么以及如何解决错误。

错误标题应包含简洁、有意义的错误摘要。错误详情应提供尽可能多的信息。
如果可能，包括原因和解决问题的说明。不要只提供系统日志或错误标题。尝试说明错误是如何引起的以及用户可以采取什么措施来修复它。假设有些用户可能不理解崩溃日志，需要更简单的描述。
编写面向人类的错误消息，不带责备。不要使用夸张的措辞或行话，避免道歉。用清晰易懂的术语提供发生错误的简要概述，并包含严重程度。
与其他 UI 元素一样，在标题和详情中使用句子大小写、通俗易懂的语言和主动语态。错误消息中不要使用“invalid”一词。必要时使用“not valid”。

另请参阅警报模态框。

使用

评估查询和表达式失败：请为警报规则添加查询目标。

避免使用

评估查询和表达式失败：[plugin.downstreamError] 查询数据失败：未找到警报规则的查询目标。

使用

请填写标有 * 的必填字段。

避免使用

看起来您遗漏了一个必填字段。

使用

服务器无响应。

避免使用

糟糕，服务器似乎正在休息中。

有关输入字段的用法和示例，请参阅 Grafana Storybook React 组件库。

输入字段验证

当文本字段有格式要求时，使用输入字段验证。如果验证失败，在字段下方直接显示错误消息。

有关带有验证的输入字段示例，请参阅 Grafana Storybook React 组件库。

警报模态框

警报模态框以吸引用户注意力的方式显示重要消息，但不会中断用户的任务。

假设有些用户可能不理解技术术语，需要简单、清晰的警报消息。与其他 UI 元素一样，警报中使用句子大小写、通俗易懂的语言和主动语态。

注意
“modal”一词被认为是行话，除非是开发者文档中引用代码中的 modal，否则不应在文档写作中使用。改用“对话框”。

严重性级别

警报模态框有严重性级别（错误、警告、信息和成功），每个级别使用不同的颜色

严重性	何时使用
	如果操作失败且阻止用户完成任务，使用错误。
	使用警告表示“不要这样做”，例如，如果该步骤可能是不可逆转的，导致永久数据丢失。
	用作注释，提供有用但不关键的信息。
	用于表示操作已完成且无错误。

可操作的说明

对于错误消息，提供可操作的说明，帮助用户成功完成任务。

使用

警告
您需要额外权限才能执行此操作。
所需权限：plugins:write

避免使用

错误
您需要额外权限才能执行此操作。

确认模态框

确认模态框用于请求用户确认操作，例如删除。确认模态框会中断用户的工作流，迫使他们在模态框中处理该操作。仅当这种中断是好的，例如错误成本很高时，才使用模态框。

在确认消息中使用带有动词的肯定操作。直接且可操作的语言鼓励用户采取下一步。
务必解释用户可以选择的操作的影响和后果。与其他 UI 元素一样，在确认消息标题和详情中使用句子大小写、通俗易懂的语言和主动语态。

使用

使用 Google 定位服务？
让 Google 帮助应用确定位置。这意味着将匿名位置数据发送给 Google，即使没有应用正在运行。

避免使用

您确定吗？

有关确认模态框的用法和示例，请参阅 Grafana Storybook React 组件库。

工具提示

工具提示用于标识 UI 对象，如图标。用户将鼠标悬停在 UI 对象上即可查看包含描述的框。

工具提示用于辅助信息，因为用户只有在将鼠标悬停在对象上时才会查看信息。
保持工具提示简短，通常少于 120 个字符。
考虑使用工具提示作为额外的应用内文档，如下例所示：

有关工具提示模态框的用法和示例，请参阅 Grafana Storybook React 组件库。

标题

标题为您的 UI 元素提供结构。无论何时需要将内容分解为分层块（通常在窗口、对话框和向导中），都可以使用标题。

标题应具体且有意义，包含最相关的关键词和内容块的主要观点，同时保持简短。
标题使用句子大小写，不带标点，必要时使用问号。将用户正在寻找的词放在标题前面，以便标题更突出。

使用

将您的数据连接到 Grafana Cloud

避免使用

将您的数据连接到 Grafana Cloud

链接

如果您的产品复杂，您可能无法在 UI 文本中简洁地提供相关详情。在这种情况下，您可以提供文档链接以获取详细信息。

谨慎使用链接。首先尝试编写简洁完整的 UI 文本。如果您包含链接，请确保引用的内容有助于用户完成他们在 UI 中正在执行的任务。
您的链接文本应具有描述性，告诉用户单击后将找到什么内容。使用链接到的主题的确切标题，以便链接断开时，用户可以搜索该主题。像标题一样，将用户正在寻找的词放在链接文本前面，以便链接更突出。
将链接放在句子的开头或结尾，而不是中间。不要将前面的冠词包含在链接文本中。
对于概览文本，您可以链接到相关的概览文档和 Grafana University 课程。

使用