文档 作家工具包 写作 风格指南 样式约定

样式约定

在撰写技术文档时，请参考这份非详尽的技术写作技巧和样式列表。如果您有本指南未涉及的问题，请参阅Google 开发者文档风格指南。

关注用户目标

在开始写作之前，请清晰地确定用户的目标，并撰写支持用户实现该目标的内容。

• 请勿记录对用户没有明确影响的实现细节、规范或后端系统操作。
  • 提供不必要的信息会导致内容冗长，迫使用户自行判断哪些内容是相关的。
• 避免使用营销套话和夸张词语。
  • 相反，请使用基于证据或可量化的语言来聚焦和提炼信息，并提供价值主张。

避免提及其他公司

在技术文档中避免提及其他公司。竞争性内容应属于市场营销材料。

在某些情况下，您必须提及其他公司，例如在数据源插件文档或迁移指南中。除此之外，请尽量避免提及。

请勿记录第三方产品

在记录我们的产品如何与合作伙伴产品集成时，请记录我们对它们的使用，但不要记录产品本身。

尽可能构建文档，以便您可以链接到第三方文档中的适当位置。

清晰地称呼用户

为了清晰直接地称呼用户，请使用第二人称（“您”）并避免使用第一人称（“我”、“我们的”或“我们”）。谨慎使用“我们的”之类的第一人称复数代词。在谈论读者时不要使用“我们”，而应使用“您”。在谈论 Grafana Labs 时可以使用“我们”。

指令应使用第二人称祈使句，其中隐含了未说出的“您”。

避免将用户或其角色（例如系统管理员）作为句子的主语，例如：“用户使用安全 shell 配置 Cloud。”。

例外

• 您可以在特定于用户的 UI 元素中使用第一人称，例如我的个人资料或我的账户。

使用主动语态写作

当您使用主动语态写作时，您确定句子的主语以及主语执行的动作。例如，“约翰开了车”是主动语态，因为明确了约翰（主语）执行了动作（开）。被动语态的变体是“车是由约翰开的。”

使用简单的词语、句子和段落

简单、直接的沟通是有效技术沟通的关键。

• 尽可能使用简短的词语，例如“使用”（use），而不是“利用”（utilize）。
  • 如果可能，将“使用”（use）及其变体（utilize, make use of）替换为更具描述性的动词。
• 确保句子少于 25 个词。
  • 如果删除某个词语不会影响意义，请将其删除（常见冗余词：there is; there are; in order to; it is important to; keep in mind）。
  • 如果您发现自己在写长句子，请考虑写更短的句子或使用项目符号列表。
• 使用简单的动词和时态。
• 选择术语时，请考虑您读者的特征。
• 不要使用流行语或行话。
• 将段落保持在三句话或更少。
  • 压缩文本，添加更多标题，或两者都做。
• 在常见和否定情况下使用缩略语以表达对话式风格：例如，您是（you’re）、那是（that’s）、不是（isn’t）或_不_（don’t）。

使内容与用户上下文相关。您越熟悉用户的上下文，就越能用简洁的语言进行沟通。

使用现在时写作

当您使用现在时写作时，避免使用 have, has, had, been, should, would 和 will 等词语。

但是，与Google 的风格指南类似，您可以在撰写教程或明确未来将发生的动作时使用将来时（will）。

保持积极

写积极的句子而不是消极的句子。积极的句子更容易让用户理解，并且通常比消极的句子短。

撰写易于扫描的内容

用户通常会扫描内容而不是阅读。长篇文字块会降低可读性，因为它们会埋藏信息。

使用以下技巧使内容更易于扫描。

• 首先写重要信息。
• 将操作放在解释之前。
• 使用简短的项目符号列表。
• 使用标题来划分内容。

列表

有关列表和表格的讨论，请参阅 Google 开发者文档风格指南中的列表页面。

有序列表

有序列表也称为编号列表。

有关在 Markdown 中编写编号列表的指南，请参阅编号列表。

无序列表

撰写无序列表时，请参考以下指南。

• 列表项应以大写字母开头，除非有充分理由不这样做。例如，当您列出区分大小写的参数时。
• 如果列表项是完整的句子，则以句号结尾。如果列表中的一个项目以句号结尾，则列表中所有项目都应使用句号。

更多指导，请参阅Google 开发者风格指南中的列表。

定义列表

定义列表常用于提供术语列表和缩进的定义。例如，您可以使用定义列表来记录命令及其含义。

Feature

创建一项功能

Features

创建多项功能

示例附加功能

要创建定义列表，请在新行上添加术语，然后在下一行添加一个冒号 (:) 以及定义。

更多信息，请参阅 Markdown 指南中的定义列表。

排序列表

列表和表格行按字母顺序排序，除非顺序对于理解列表或表格中的信息很重要。

链接和引用

引用其他文档时，您应该使用参考（refer to），而不是参见（see）或查看（check out）。

让读者了解引用的内容。不要使用通用引用，例如“参考 [此文件]”。

尽可能使用您链接到的页面或章节的确切标题作为链接文本。

例如

markdown 复制

For more information about Grafana Labs products, refer to [Grafana documentation](/docs/grafana/latest/).

有关更全面的指导，请参阅编写有用的链接文本

数字

有关数字样式的指导，请遵循Google 风格指南，但序数除外。序数是表示某事物相对于其他数字的位置或顺序的数字，如 first, second, third 等。

对于序数，将 first 到 ninth 写出。对于 10th 及以上，使用数字。

提示框 (Admonitions)

为了吸引用户的注意力，Grafana Labs 文档包含注释、警告和危险警告。

为了标准化样式，每个提示框都有一个特殊的短代码声明。以下各节提供了如何编写每种类型的示例。有关完整的语法参考，请参阅短代码。

注释 (Notes)

注释提供了用户应该了解的附加信息。注释是最常见的提示框。

注释提示框的语法如下：

markdown 复制

{{< admonition type="note" >}}
This page describes a feature for Grafana 9.0 beta.
{{< /admonition >}}

在发布的页面上，此注释显示如下：

警告 (Cautions)

警告（Caution）提醒用户谨慎操作。警告强调了行动的潜在不利方面。

警告提示框的语法如下：

markdown 复制

{{< admonition type="caution" >}}
By disabling authentication requirements, anyone can access your Grafana instance.
There is a considerable security risk associated with this.
{{< /admonition >}}

在发布的页面上，此警告显示如下：

危险警告 (Warnings)

危险警告（Warning）告知用户不要执行某项操作。危险警告仅用于可能对硬件、软件或数据造成损害的操作。

危险警告提示框的语法如下：

markdown 复制

{{< admonition type="warning" >}}
Don't back up your dashboards in Grafana.
You might not be able to recover a dashboard if it's deleted.
{{< /admonition >}}

在发布的页面上，此危险警告显示如下：

语义换行符

语义换行符组织建议在写作中添加语义换行符。在每个句子后添加换行符，可以更容易理解源文本的形状和结构。

带有换行符

markdown 复制

When you write in active voice, you identify the subject of the sentence and the action that the subject performs.
For example, "John drove the car" is active voice because it is clear that John (the subject) performed an action (drove).
The passive voice variation is "The car was driven by John."

不带换行符

markdown 复制

When you write in active voice, you identify the subject of the sentence and the action that the subject performs. For example, "John drove the car" is active voice because it is clear that John (the subject) performed an action (drove). The passive voice variation is "The car was driven by John."

这两种情况下的 HTML 输出是相同的。但是，第一种更容易评审和编辑，并且受每个贡献者屏幕和文本编辑器设置的影响较小。

文本格式

对粗体、斜体和其他文本格式采取一致的方法是一个好主意。

粗体

直接引用 UI 元素时使用粗体格式 (**)。

当您引用抽象的 UI 元素（例如角色：Admin、Editor、Viewer）时，而不是直接引用 UI，请勿将词语加粗。将词语的首字母大写，并将其用作形容词，后跟其描述的名词。例如：

markdown 复制

Users with the Viewer role can't edit settings.

您可以在表格中将粗体与其他散文内联使用，但不要对单元格的全部内容使用粗体，即使它是 UI 元素。例如：

您可以在无序列表中的第一个句子使用粗体，后跟更多信息。

• 事物：关于该事物的信息。

使用粗体表示 Web 应用内的路径，并使用大于号 (>) 表示路径分隔符。例如：

markdown 复制

To add an administrator to the list of local users, navigate to **Appliance** > **Configuration** > **Access**.

不要使用粗体突出句子中的某个词语或短语，而是使用斜体强调。

斜体

使用斜体格式 (_) 强调特定词语或短语。这在首次定义术语时特别有用。

例如

Prometheus 数据模型被组织成由时间戳和样本组成的指标。

代码

使用代码格式 (`) 引用：

• 文件名
• 配置选项
• 用户输入
• 文本/内联代码
• 类名和方法名、状态码和控制台输出