文档 Writers' Toolkit 写作 风格指南 大小写和标点符号

大小写和标点符号

本节包含大小写和标点符号指南。

大小写

使用句子大小写书写标题。

写作时请参考以下大小写指南。

句子大小写

句子大小写将标题的第一个词和所有专有名词的首字母大写。

这种风格主要采用小写，被认为是最快的阅读形式。

缩写词大写

缩写词使用全部大写，例如 API、HTTP、ID、JSON、SQL 或 URL。

专有名词大写

人、地点和产品的名称首字母大写，因为它们是专有名词。

如果不确定某事物是否是产品，请咨询产品经理；如果没有产品经理，则咨询负责的小组。

Grafana 特有的大小写指南

• 菜单和子菜单标题始终使用句子大小写：第一个词首字母大写，其余小写。
  • 指的是子菜单标题时使用 Dashboards。
  • 指的是子菜单主题时使用 Keyboard shortcuts。
• 通用和复数形式始终使用小写。
  • 一般提及仪表盘时使用小写 dashboard。
  • 提及多个仪表盘时使用小写 dashboards。
• 例外：如果某个术语在 Grafana UI 中是小写，则与其保持一致。
• 当您提及抽象的 UI 元素，例如角色（Admin、Editor、Viewer），但不直接引用 UI 时，请勿将该词加粗。将该词首字母大写，并将其用作形容词，后跟它所描述的名词。例如：
  • 具有 Viewer 角色的用户无法编辑设置。

Kubernetes 对象

提及 Kubernetes 对象时，例如 Jobs、Pods 和 StatefulSets，请遵循Kubernetes 文档风格指南中的指导。对象首字母大写可以清楚表明您不是在谈论一般的作业或部署。

首次使用时，将对象介绍为 Kubernetes XX，之后可以直接使用对象名称。

示例

• 创建 Kubernetes Job 并检查日志以检索生成的 token
• 该 Job 需要 token

Amazon 产品

提及 Amazon 产品时，例如 Amazon CloudWatch，请包含“Amazon”前缀。首次使用后，您可以只使用产品名称。

在标题中，始终使用包含“Amazon”的完整名称。

Apache 项目

提及 Apache 项目时，例如 Apache Mesos，请包含“Apache”前缀。首次使用后，您可以只使用项目名称。

在标题中，始终使用包含“Apache”的完整名称。

Google 产品

提及 Google 产品时，例如 Google Kubernetes Engine，请包含“Google”前缀。首次使用后，您可以只使用产品名称。

在标题中，始终使用包含“Google”的完整名称。

标点符号指南

撰写技术内容时请参考以下标点符号指南。

• 句号后添加一个空格，而不是两个。
• 列举系列项目时，在 and 或 or 之前插入逗号。这被称为使用系列逗号或牛津逗号。
  • 示例：“午餐时，他们享用了乳蛋饼、藜麦和羽衣甘蓝沙拉。”
• 不要用连字符号（&）缩写 and。
  • 例外：如果 UI 使用连字符号，则与其保持一致。