文档样式指南

本文档提供了 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 lint 工具：

fx lint

标头

页面和版块标题采用句首字母大写形式

所有标题和版块标题（#、##、###）都必须使用句首字母大写。

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

# 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 上，DevSite 的 Markdown 解析器不允许列表在没有前置空行的情况下中断活动段落。如果省略空行，整个列表（包括子项、嵌套子列表和代码块）会折叠到前面的段落中，形成一个未格式化的文本块。

列表中的各个项之间无需空行。紧凑列表（连续项之间没有空行）完全受支持，建议用于简洁项。在列表项之间添加空行是可选的，通常只有在列表项包含多个段落、嵌套代码块或复杂子元素时才需要。

建议：简洁的列表，列表前后有空行：

To configure your build, complete the following steps:

1. Select your target device.
2. Build the package.

Once the build finishes, you can proceed to testing.

不推荐：列表前后没有空行：

To configure your build, complete the following steps:
1. Select your target device.
2. Build the package.
Once the build finishes, you can proceed to testing.

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

使用受支持的 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 上，章节标题（##、###）提供了足够的视觉分隔和结构，无需使用装饰性水平线。

代码示例

在代码块前后添加空行

始终在围栏代码块 (```) 的开头围栏之前和结尾围栏之后添加一个空行。这样可以确保散文段落、列表项和代码示例之间清晰分隔，并防止 Markdown 解析器将后续文本不当分组到代码块中。

建议：在代码块周围添加空行：

Run the following command to start the emulator:

```posix-terminal
ffx emu start
```

Once the emulator is running, proceed to the next step.

不建议：代码块前后没有空行：

Run the following command to start the emulator:
```posix-terminal
ffx emu start
```
Once the emulator is running, proceed to the next step.

使用 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