文档 Writers' Toolkit 写作 样式指南 包容性写作

包容性写作

为 Grafana Labs 写作时，务必使用包容性术语和措辞。避免所有会延续性别、种族或文化刻板印象的陈述。不要使用与内容无关的性别或基于人口统计的术语。

关于人的写作

在描写人物时，请保持同情心、包容性和尊重。

无论在何种语境下，我们始终确保将人视作人。考虑到这一点，不同的人与我们的产品互动方式存在重要的区别，因此我们也需要区分如何指代这些人。

• 用户是使用我们产品的每个人，无论他们是否使用我们产品的商业版本。客户是为使用我们产品付费的个人和公司。
• 访问者出于任何原因访问我们网站的人，无论是潜在用户、客户还是员工。我们感谢所有对我们辛勤工作的关注。
• 我们的客户（和用户）通常有他们自己的客户（和用户）。通常情况下，我们将这些客户的客户称为用户。
• 员工是在 Grafana Labs 工作的人。

最佳实践

请考虑以下最佳实践，以确保写作的包容性。

• 群体或受众：不要将群体或受众称为 it。请改用 they。
• 年龄：除非相关，否则不要提及某人的年龄。不要使用与年龄相关的词语来描述人。避免使用：young（年轻的）、old（年老的）或 elderly（年长的）。
• 听力：在描述有听力障碍的人时，请使用形容词 deaf（聋）、partially deaf（部分聋）或 hard of hearing（听力困难）。
• 视力：在描述视力有限的人时，请使用形容词 blind（盲）或 low vision（低视力）。

为国际受众写作

Grafana Labs 使用美式英语作为拼写、语法、标点符号等的标准。我们为国际受众写作时遵循以下指南

避免使用缩写词

如果您使用缩写词，请在首次使用时写出缩写词中的每个单词，然后继续只使用缩写词。

• 示例：Grafana Cloud 是软件即服务 (SaaS)。使用 SaaS 通常需要设置账户。

避免使用习语

理解习语通常需要文化背景。Grafana Labs 产品和项目的用户遍布全球，其中许多人不是英语母语者。因此，请避免使用习语和习语双关语。

例如，一些常见的美国英语习语

• Costs an arm and a leg
• Hit the nail on the head
• Bite off more than you can chew

这里还有一些更生僻的英式习语

• A few sandwiches short of a picnic
• Chuffed to bits
• Over-egg the pudding

避免文化引用

文化引用是指与社区、国家、大陆等文化相关的引用。

示例

• Her ambition is a clear reflection of the American dream.
• You came to help like a good Samaritan.
• They grew up in a typical nuclear family.

避免使用带有倾向性的语言

避免使用带有倾向性的语言，例如 blacklist（黑名单）、master（主）、和 slave（从）。

允许，阻止

避免使用 whitelist 或 blacklist。

在提及允许或阻止内容或流量时，请使用 allow 或 block 的某种形式

• 对于名词形式，请使用 allowlist 或 blocklist
• 对于动词形式，请使用 allow 或 block

示例：要 允许 传出流量，请将 IP 添加到 allowlist。

主和备

避免使用 master 或 slave。

使用以下方法描述节点或进程之间的关系

• 使用 primary（主）、main（主）或 parent（父），而不是 master。
• 使用 secondary（备）、replica（副本）或 child（子），而不是 slave。

右和左

使用 right（右）和 left（左）时，可加上 top（上）或 lower（下）等限定词，以帮助有认知障碍或使用屏幕阅读软件的人。

当您修饰名词时，请使用连字符。例如

• in the top-right corner
• at the bottom left of the dialog box
• the upper-left section
• scroll toward the lower right

不要使用 hand 作为限定词，例如 right-hand corner。