文档 撰写工具包 撰写 风格指南 面向开发人员编写文档

面向开发人员编写文档

以下指南为面向软件开发人员和工程师编写文档提供了建议。遵循这些技巧可以编写有用的 API 文档、代码示例和其他技术材料。要了解如何与增强和使用 Grafana Labs 项目或产品代码的开发者有效沟通，请结合风格指南阅读本指南。

开发者文档基础知识

为软件开发人员编写技术内容与为软件产品的用户或管理员编写内容类似，因此适用相同的通用指南。然而，面向开发人员的文档通常更具技术性，并依赖于某些重要的约定。由于此类文档包含代码的详细信息，因此了解如何构建、格式化和识别可能出现的常见问题非常重要。

当您的读者是开发者时，您可以假定他们熟悉一般的编程概念。无需解释基础概念。相反，请介绍 Grafana Labs 产品特有的概念和功能。例如，与其涵盖 *一般* UI 设计的基础知识，不如解释 Grafana Labs 软件或 API *如何*解读这些原则。

代码注释

良好文档的基础是简洁、相关且最新的代码注释。

关于编写注释的注意事项，请参阅`grafana-*` 包中代码注释的指南。

更多通用建议，请查阅适用于您编程语言的知名Google 风格指南。

参考文档

如果可能，从源代码注释中自动生成 API 和其他参考文档。无论文档如何创建，请确保其符合风格约定。请特别注意正确格式化代码元素。

自动生成的文档

通过编程方式自动化文档的优势众所周知，包括提高一致性和减少人为错误。但每行自动生成的内容背后都有一个人类作者，他们负责遵循风格指南。

在编写用于自动生成程序创建可发布内容的文档时，请记住以下几点

自动生成工具可以解析语法，但在编写用于创建自动化内容的文档时，您需要负责添加可操作的洞察。

• 有哪些注意事项、边缘情况和副作用？
• 代码中不言自明的全局概览是什么？
• 简而言之，开发者需要了解哪些才能使用该代码？

API 参考文档元素

正确记录 API 参考文档中最常见的元素，例如标题、参数、返回值等。以下建议可帮助您编写更完整和一致的文档

其他提示

• 请记住简洁书写的原则。当您可以说“添加用户。”时，不要说“此方法添加用户。”如果您的 linter 要求描述以元素名称开头，您可以说“AddUser 方法添加用户。”以避免错误消息。
• 当代码元素的名称是单数时，不要将其变为复数。而是添加一个复数名词来描述它们。例如，不要将 `MyEvent` 改为 `MyEvents`；应提及 `MyEvent` 对象。
• 如果元素执行某种操作，则将描述的第一句话以一个动作动词开头。

参考文档结构

按字母顺序组织参考文档，按使用频率组织过于主观。

如果参考文档包含必需和可选组件，请分别记录。先记录必需组件，然后记录可选组件。按字母顺序组织每个组件集。

代码示例

文档读者通常会快速浏览，寻找可以直接复制粘贴运行的代码示例。因此，尽可能提供生产环境可用的示例。

但是，并非每个代码示例都必须能在生产环境中运行。一些代码示例是为了说明某一点，以便开发者可以学习如何自行完成类似的操作。此类示例应明确标记为部分示例。

提供示例时，请给出书面描述。您可以将其放在文档正文中，或作为解释性注释放在示例代码中。然而，不要在命令行示例中放置注释。

记住基本原则：解释您的代码*为什么*这样做，而不是描述它*做了什么*。关于编写开发者文档的深入外部资源，请参考《开发者文档》。

完整代码示例

要格式化代码示例，请使用以下指南。

语法高亮

在 Markdown 中，第一个三个反引号之后的信息字符串描述了其中包含的语言。网站使用此信息为代码示例应用语法高亮。

以下 Markdown 将信息字符串设置为 `json`

markdown 复制

```json
{ "key": "value" }
```

一些常见的语言及其信息字符串如下

• Bash: `bash`
• Console: `console`
• Go: `go`
• JSON: `json`
• PromQL: `promql`
• River: `river`
• Shell: `shell`
• YAML: `yaml`

使用适当的空白进行缩进

空格 (` `) 是一个好的默认选择，但请注意一些语言使用替代缩进。例如，Makefiles 和 Go 源代码使用制表符 (` `) 进行缩进。

使用 2 个空格，除非有明确建立的替代约定。例如，Python 通常使用 4 个空格进行缩进。

最重要的是，与您所在文档区域或项目中的现有文档保持一致。

用一句或一段话介绍每个代码示例，以建立其上下文

如果介绍紧接在示例之前，则以冒号 (`:`) 结束；否则，以句号 (`.`) 结束。

使用 `code` Shortcode 创建带选项卡的示例

如果您在多种语言中有相同的示例，请使用`code` Shortcode。网站将代码片段呈现在选项卡中，并记住用户的首选。

部分代码示例

部分代码示例更短，将读者的注意力集中在代码的特定区域。然而，它们需要用户将部分代码示例与现有的配置或其他示例集成。

除了代码示例格式化的一般指南外，处理部分代码示例时，请遵循以下指南。

尽可能确保部分示例可复制粘贴

在 JSON 或 YAML 中，部分示例本身应该是有效的。

在编程语言的代码示例中，如果示例本身无法编译，请确保代码片段是源文件中可识别的单元。

不要使用省略号 (`…`) 或三个句点 (`...`) 来省略信息。

它会破坏读者复制粘贴示例的功能，并且不会为省略提供额外的上下文。请改为使用前面的句子或有效的代码注释来清楚地解释示例的范围以及省略的内容。

例如

以下 YAML 示例演示了使用 `TCP` 协议配置编号为 `80` 的单个端口。

它是 Kubernetes Service 规范的一部分。它不是一个完整的 Service 规范，您必须将其与 Service 规范的其余部分合并。

yaml 复制

ports:
  - port: 80
    protocol: TCP

解释如何集成示例

尤其是在 YAML 示例中，解释如何将示例集成到更广泛的配置中非常重要。

解释示例是哪个键的值。以下示例扩展了上一节中的示例

以下 YAML 示例演示了使用 `TCP` 协议配置编号为 `80` 的单个端口。

它是 Kubernetes Service 规范的一部分。它不是一个完整的 Service 规范，您必须将其与 Service 规范的其余部分合并。

要合并该示例，您必须将其包含为 Service `spec` 映射的值。如果存在现有的 `ports` 值，您必须选择替换它或合并两者。

yaml 复制

ports:
  - port: 80
    protocol: TCP

引用嵌套字段

对于 JSON 或 YAML 中的配置，您可能需要引用深度嵌套的字段。使用自然语言编写和阅读都非常费力。

相反，使用点表示法分隔嵌套字段。例如，`spec.template.metadata` 指代位于 `template` 字段内的 `metadata` 字段，而 `template` 字段本身位于 `spec` 字段内。

如果字段名包含点，则改用方括号将其括起来。例如，`spec.selector[app.kubernetes.io/name]`。

要引用数组中的任何成员，请使用 `[*]`。

要引用数组中的特定索引，请使用 `[<INDEX>]`。例如，以下点表示法指代 `spec` 中的第一个容器及其中的第一个端口：`spec.containers[0].ports[0].containerPort`。

在其他工程文档（例如Kubernetes 文档）中，对嵌套字段使用点表示法是很常见的。

路径、文件名和 URL

多种类型的信息应使用等宽字体。其中包括路径、文件名、目录和文件夹。但是，如果您打算用户点击链接，请不要将域名或 URL 格式化为代码。

命令行

在技术内容中包含命令行命令时，请遵循以下约定。

• 不要假定所有人都使用 Linux。确保说明包含足够的信息，以便 Windows 和 Mac 用户也能成功完成操作。

• 不要在命令前添加 `$`，以便用户可以直接复制粘贴。

  • 正确：`sudo yum install grafana`
  • 错误：`$ sudo yum install grafana`

• 对于需要 `sudo` 才能工作的命令，请在命令前包含 `sudo`。

对于终端示例和配置，使用 `bash` 代码块。在原始 Markdown 中

markdown 复制

```bash
sudo yum install grafana
```

产生如下输出

bash 复制

sudo yum install grafana

如果您的命令行说明包含输入和输出行的组合，请对输入和输出使用单独的代码块，并使用 `console` 代码块表示输出。

输入（原始 Markdown 格式）

markdown 复制

```bash
cat ~/.ssh/my-ssh-key.pub
```

产生如下输出

console 复制

cat ~/.ssh/my-ssh-key.pub

对于 HTTP 请求/响应，在原始 Markdown 中使用 `http` 代码块

markdown 复制

```http
GET /api/dashboards/id/1/permissions HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

产生如下输出

http 复制

GET /api/dashboards/id/1/permissions HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

如果参数是可选的，请用方括号将其括起来。对于必需参数，请参阅占位符变量。例如，建议使用以下原始 Markdown

markdown 复制

```bash
ssh-rsa <KEY_VALUE> <USERNAME> [FILENAME]
```

产生如下输出

bash 复制

ssh-rsa <KEY_VALUE> <USERNAME> [FILENAME]

占位符变量

在包含占位符时使用描述性词语和短语，避免使用 X 或 XXX。在 Markdown 中，在占位符前面，使用下划线 (`_`) 后跟反引号 (` `) 和小于号 (`<`)。在占位符末尾，使用大于号 (`>`) 后跟反引号 (` `) 和下划线 (`_`)。

例如，请参阅以下原始 Markdown

Markdown 复制

The following text is a placeholder: _`<PLACEHOLDER>`_.

产生如下输出

以下文本是占位符：<PLACEHOLDER>。

有关命令行格式的更多信息，请参阅 Google 的文档命令行语法指南。