文档样式指南

本文档为 Fuchsia.dev 提供了写作风格指南。这些准则以 Google Developers 样式指南中的一般准则为基础。

本指南内容：

• 语气、声音和语法
• 大纲和导航列表
• 文字和链接
• 标题
• 列表
• 标注（注释、警告和提示）
• 水平分隔线
• 代码示例

语气、声音和语法

撰写 Fuchsia 文档时，请遵循以下样式、语气和语法指南，以确保内容清晰、一致且易于理解。

使用纯正的美式英语

使用简单字词和简洁句子，以清晰直接的美式英语撰写内容。 使用标准缩略形式（例如 it's、don't、you'll）营造自然亲切的语气。避免使用非英语母语者可能难以翻译的习语、区域性口语或俚语。

使用第二人称（“您”）称呼读者

直接使用第二人称（“你”）向读者写作。

建议：使用第二人称直接与开发者对话：

You can install Fuchsia by running the following command:

不建议：避免使用第三人称短语（“用户可以”）或第一人称复数（“我们可以”）：

Fuchsia users can install the OS, and then we can run the test.

使用现在时和主动语态

以现在时态陈述事实和系统行为。避免使用将来时（“将”），以免造成行动发生时间的歧义。 此外，请使用主动语态而非被动语态，以便明确执行操作的主体。

建议：使用主动语态和现在时：

The command creates a configuration file in the working directory.

不建议：使用被动语态和将来时：

A configuration file will be created by the command.

拼写出缩写并使用一致的术语

在文档中首次提及缩写词时，请拼写出全称，然后在括号中附上缩写词（例如，“Looks Good To Me [LGTM]”）。确保技术术语与官方 Fuchsia 词汇表一致。

大纲和导航列表

包括顶级大纲和子部分列表

长篇文档或包含多个部分的文档应提供导航列表，以帮助读者了解文档结构：

• 在文档顶部附近（简介之后和第一个 ## 部分标题之前）添加一个顶级大纲导航列表。

• 在包含多个子部分 (###) 的主要部分（## 标题）顶部添加子部分步骤列表。

确保顶级大纲不冗余

顶级大纲导航列表应仅列出主要部分（## 标题）。如果子版块 (###) 已列在相应主要版块的顶部，请勿将子版块链接嵌套在顶级大纲中的主要版块项下。保持顶部轮廓的简洁性可避免冗余。

选择编号导航列表或项目符号导航列表

仅当部分内容需要按顺序执行时（例如在教程或方法指南中），才使用编号列表项 (1. [Section title](#anchor))。对于顺序过程，请在导航列表前添加 "The steps are:"。

推荐：顺序流程的顶级大纲：

The steps are:

1. [Prerequisites](#prerequisites)
2. [Build Fuchsia](#build-fuchsia)
3. [Set up Device Cloud](#set-up-device-cloud)
4. [Troubleshooting](#troubleshooting)

对于非顺序主题（例如概览、概念页面、索引页面或参考文档），请使用项目符号列表项 (* [Section title](#anchor))。如果版块不是按顺序排列，请勿添加 "The steps are:"。

建议：非顺序参考或概览文档的顶级大纲：

* [Overview](#overview)
* [Available skills](#available-skills)

对于包含多个子部分的主要部分，请在该部分顶部提供子部分列表：

## Set up Device Cloud {:#set-up-device-cloud .numbered transformation="converted"}

1. [Set up environment](#set-up-environment)
2. [Check out device](#check-out-device)
3. [Recover and flash](#recover-and-flash)
4. [Serve packages](#serve-packages)

文字和链接

遵循 80 个字符的限制

在 Fuchsia 项目中，代码的行长度上限为 100 个字符，而文档的行长度上限为 80 个字符。将所有散文行的长度限制为 80 个字符。

此规则的显著例外情况是网址、参考链接定义（例如 [reference-id]: https://...）和顶级 YAML 前置元数据，这些内容会保留在单行中，而不会换行。

代码往往会缩进（页面左侧留有空白空间），而英语散文（文档）往往会形成文本段落。这种差异会导致不同的宽度规范。

标记外部链接

使用 {:.external} 标记不在 fuchsia.dev、fuchsia.googlesource.com 或 fuchsia-review.googlesource.com 中的任何链接：

This is an [external](http://example.com){:.external} link.

请注意外部链接图标：这是一个外部链接。

使用参考样式链接

一般来说，Fuchsia 建议在 Markdown 文件中使用参考样式链接。 参考样式链接使用与链接关联的参考标识符，然后在文档中使用链接时引用该标识符。这样一来，您就可以轻松更新文档中的链接。

推荐：在您希望添加链接的位置创建标识符。

在此示例中，链接标识符名为 fuchsia-home：

Welcome to the [Fuchsia home page][fuchsia-home].

然后在文档底部定义它：

[fuchsia-home]: https://fuchsia.dev/

不建议：采用以下方式撰写内嵌链接：

Welcome to the [Fuchsia home page](www.fuchsia.dev).

您可以在外部 Markdown 指南中详细了解参考样式链接。

使用指向不同 Fuchsia 内容的正确链接

在 Fuchsia 文档中，您可以链接到以下三种类型的内容：

• /docs/ - 指向 Fuchsia 源代码树的 /docs/ 目录中的文档的链接。这些链接必须指向扩展名为 .md 的文件。例如，/docs/concepts/README.md。

• 源代码 - 指向 Fuchsia 源代码树中存在的源代码文件的链接。这些链接可以链接到任何文件扩展名，但这些文件必须存在于源代码树中。例如，/sdk/lib/fdio/fdio.cc。

• 参考文档 - 指向自动生成的 Fuchsia 参考文档的链接。

  • 大多数 Fuchsia 参考文档都不存在于源代码树中，而是发布在 fuchsia.dev 上。这些链接必须用作完全限定的网址。例如，https://fuchsia.dev/reference/fidl/fuchsia.io。
  • 不过，源代码树中存在一些 Fuchsia 参考文档。这些文档位于 /docs/reference/ 中，并发布在 https://fuchsia.dev/fuchsia-src/reference/ 部分。这些链接必须指向扩展名为 .md 的文件。例如，/docs/reference/fidl/bindings/overview.md。

在提交更改之前测试链接

创建有效的 Markdown 文档后，请运行 doc-checker 以确保您的文档使用有效的链接。当您尝试提交包含 .md 文件的更改时，Gerrit 会运行 doc-checker，如果存在失效链接，则会阻止提交。

如需在本地运行 doc-checker，请使用 fx format-code 工具：

fx format-code

标头

以句子格式编写网页和部分标题

所有标题和部分标题（#、##、###）都必须使用句子首字母大写格式。

推荐：使用句首字母大写的形式。

# This title is an example of sentence case

不建议：使用词首字母大写：

# This Title is an Example of Title Case

请勿在网页和部分标题中使用英文反引号

请勿使用反引号 (`) 来设置网页和版块标题（#、##、### 等）中的代码格式。标题中的代码格式设置不一致，会使网页的目录和导航变得杂乱无章，并进入自动生成的锚点。在标题中以纯文本形式撰写代码术语，并在后面的正文中采用代码格式。

建议：在标题中以纯文本形式写入代码术语：

# BUILD.bazel files style guide

## Avoid package default_visibility

不建议：在标题中使用反引号设置代码术语的格式：

# `BUILD.bazel` files style guide

## Avoid package `default_visibility`

锚点使用短划线，而不是下划线

默认情况下，fuchsia.dev 会使用下划线 (_) 代替空格来创建锚点。为部分标题创建自定义锚点时，请使用短划线 (-) 而不是下划线，使用 {#section-title}（或 {:#section-title}）。此外，请使用短划线作为文件名。

推荐：使用短划线作为锚点：

## This is a section header {:#this-is-a-section-header transformation="converted"}

请勿向网页标题添加自定义锚点

主页面标题（1 级标题 #）不需要自定义锚点。 自定义锚点应仅应用于子版块标题（##、###）。从 # Title 行中移除所有自定义锚点（例如 {#anchor-name}）。

列表

在列表项之间添加空行

在项目符号列表和编号列表中，请在各个项目之间添加空行，以便在 fuchsia.dev 上获得良好的可读性和呈现效果。此外，请在父列表项与嵌套子列表的开头之间添加空行。

建议：在项之间和子列表之前添加空行：

* First list item.

* Second list item.

  * First nested sub-list item.

  * Second nested sub-list item.

不推荐：连续的列表项之间没有空行：

* First list item.
* Second list item.
  * First nested sub-list item.
  * Second nested sub-list item.

标注（注释、警告和提示）

使用受支持的 DevSite 标注语法来突出显示 fuchsia.dev 上的重要信息。如需创建标注框，请以受支持的 DevSite 标注关键字之一开头，后跟英文冒号 (:) 来开始一个段落：

• Note: ...
• Caution: ...
• Warning: ...
• Important: ...
• Tip: ...

保持标注框简洁明了。注释和其他标注通常应包含单个段落或简短的句子。请勿将项目符号列表或编号列表放在标注框内。

建议：使用 DevSite 宣传信息语法，并保持宣传信息内容简洁明了：

Note: This is an example of a concise DevSite note callout box.

Warning: Running this command overwrites existing configuration files.

不建议：请勿在标注中添加列表，也不要使用不受支持的提醒格式：

• 请勿将项目符号列表或编号列表放在标注框内。

• 请勿使用 GitHub 样式的块引用提醒（例如 > [!NOTE]、> [!TIP] 或 > [!WARNING]）。DevSite 不支持这些提醒。

• 请勿使用粗体或斜体的引导文字（例如 **Note:** 或 _Note:_）。这些文字会呈现为正文，而不是标注框。

  **Note:** Do not use bolded lead-ins.
  

水平分隔线

请勿在 Markdown 文档中使用 --- 水平标尺或分隔线。 在 fuchsia.dev 上，部分标题（##、###）提供了足够的视觉分隔和结构，无需装饰性水平线。

代码示例

使用 posix-terminal 作为 shell 命令示例

推荐：通过在 shell 命令的 ``` 之后添加 posix-terminal，让读者可以轻松复制代码块中的内容。

```posix-terminal
fx ota
```

此代码块在命令前面添加了 $：

fx ota

不建议：请勿在命令中对 $ 字符进行硬编码。

$ fx ota

停用复制功能

建议：对于不应复制的代码或输出日志示例，请在 ``` 后面添加 none 或 none {:.devsite-disable-click-to-copy}。

```none {:.devsite-disable-click-to-copy}
$ my_command
It won't be necessary to copy and paste this code block.
```

此代码块在呈现时，右上角没有复制图标：

$ my_command
It won't be necessary to copy and paste this code block.

不推荐：为仅供查看的内容启用复制功能。如果您未在 ``` 之后指定任何内容，则默认启用复制功能。

```
$ my_command
It won't be necessary to copy and paste this code block.
```

此代码块的呈现效果如下：

$ my_command
It won't be necessary to copy and paste this code block.

引用源代码时使用路径而非网址

推荐：引用源代码的所有链接都应仅通过路径引用。否则，您将收到静态错误检查。

Update the [state header][sh]
[sh]: /zircon/system/ulib/inspect/include/lib/inspect/cpp/vmo/state.h