感谢您为 Bazel 的文档贡献力量。本文档可作为一份快速的文档风格指南，帮助您快速上手。对于本指南中未解答的任何样式问题，请遵循 Google 开发者文档样式指南。
定义原则
Bazel 文档应坚持以下原则：
- 简洁。使用尽可能简短的字词。
- 清除。使用通俗易懂的语言。达到五年级阅读水平，而不用专业术语来写。
- 稳定。在整个文档中，对重复的概念使用相同的字词或短语。
- 正确。编写的内容尽可能长时间保持正确状态，避免基于时间的信息和对未来的承诺。
编写
本部分包含基本的书写技巧。
标题
- 网页级标题从 H2 开始。（H1 标题用作网页标题。）
标题应尽可能简短。这样，它们就能纳入 TOC 而无需封装。
- 是：权限
- 否：有关权限的简要说明
在标题中使用句首字母大写形式
- 是：已设置您的工作区
- 否：设置您的 Workspace
尽量使标题与任务相关或富有实用价值。如果标题是概念性的，则可能基于理解，但要写明用户执行的操作。
- 是：保留图表顺序
- 否：保留图表顺序
姓名
将专有名词（如 Bazel 和 Starlark）大写。
- 是：在构建结束时，Bazel 会输出所请求的目标。
- 否：在构建结束时，bazel 会输出所请求的目标。
保持一致。不要为现有概念引入新名称。在适用的情况下，请使用术语表中定义的术语。
- 例如，如果您要在终端上发出命令，请不要在页面上同时使用终端和命令行。
页面范围
每个页面都应该有 1 种用途，并且在开头应明确其用途。这有助于读者更快地找到所需内容。
- 是：本页将介绍如何在 Windows 上安装 Bazel。
- No：（没有介绍性句子。）
在页面底部，告诉读者接下来该怎么做。对于没有明确操作的网页，您可以添加指向类似概念、示例或其他途径的链接以供探索。
主题
在 Bazel 文档中，受众群体应该主要是用户，即使用 Bazel 构建软件的人。
将您的读者称为“您”。（如果出于某种原因您不能使用“您”，请使用中性语言，例如。）
- 是：如需使用 Bazel 构建 Java 代码，您必须安装 JDK。
- 可以：如果用户要使用 Bazel 构建 Java 代码，必须安装 JDK。
- 否：要使用 Bazel 构建 Java 代码，用户必须安装 JDK。
如果您的受众群体不是一般 Bazel 用户，请在页面开头或此部分定义受众群体。其他受众可能包括维护者、贡献者、迁移者或其他角色。
避免使用“我们”。用户文档中没有作者；只需告诉人们可能的情况即可。
- 是：随着 Bazel 的不断发展，您应该更新代码库以保持兼容性。
- 否：Bazel 正在发展中，我们将对 Bazel 做出一些更改，这些更改有时不兼容，需要 Bazel 用户进行一些更改。
时间
尽可能避免使用具有时效性的字词，例如引用特定日期（2022 年第 2 季度）或提及“现在”“当前”或“即将”。这些值会很快过时，如果它是未来的预测，则可能不正确。请改为指定版本级别，例如“Bazel X.x 及更高版本支持 <feature> 或 GitHub 问题链接。
- 是：Bazel 0.10.0 或更高版本支持远程缓存。
- 否：Bazel 很快将支持远程缓存，可能在 2017 年 10 月。
时态
使用现在时。除非为了清晰起见而绝对必要，否则避免使用过去时或将来时。
- 是：Bazel 会在发现不符合此规则的依赖项时发出错误。
- 否：如果 Bazel 发现了不符合此规则的依赖项，则会发出错误。
尽可能使用主动语态（主语为主语动词），而不是被动语态（主语为主语动词）。一般来说，主动语态会使句子变得更清晰，因为它可以显示谁要负责。如果使用主动语态会削弱清晰度，请使用被动语态。
- 是：Bazel 会启动 X 并使用输出来构建 Y。
- 否：X 由 Bazel 启动，之后 Bazel 会使用输出构建 Y。
语气
用商务友好的语气来撰写内容。
避免使用口语化的语言。翻译特定于英语的短语较难翻译。
- 是：良好的规则集
- 否：什么是好的规则集？
避免使用过于正式的语言。就好像您在向对技术好奇但不知道细节的人解释这个概念一样。
格式设置
文件类型
为确保可读性，请在 80 个字符以内换行。较长的链接或代码段可能较长，但应另起一行。例如：
链接
使用描述性链接文字，而不是“此处”或“下面”。这种做法可以更轻松地扫描文档，并且更适合屏幕阅读器。
- 是：如需了解详情，请参阅 [安装 Bazel]。
- 否：如需了解详情，请点击 [此处]。
如果可能的话，请用链接结束句子。
- 是：如需了解详情，请访问 [link]。
- 否：访问 [link] 了解详情。
列表
- 使用有序列表来描述如何通过步骤完成任务
- 使用无序列表列出并非基于任务的内容。（仍应按字母顺序排列，例如按字母顺序、重要性等排序。）
- 采用并行结构书写。例如：
- 将列表项中的所有项设置为句子。
- 以相同时态的动词开头。
- 如果需要遵循相关步骤，请使用有序列表。
占位符
使用尖括号表示用户应更改的变量。在 Markdown 中，使用反斜杠对尖括号进行转义：
\<example\>。- 是：
bazel help <command>：<command>的打印帮助和选项 - 否：bazel help command：输出“command”的帮助和选项
- 是：
使用在上下文中有意义的占位符，尤其是对于复杂的代码示例。
目录
使用网站支持的自动生成的 TOC。不要手动添加 TOC。
编码
代码示例是开发者最好的朋友。您可能已经知道如何编写这些代码，但这里有一些提示。
如果您要引用一小段代码，则可以将其嵌入句子中。如果您希望读取器使用代码（例如复制命令），请使用代码块。
代码块
- 简明扼要。从代码示例中剔除所有冗余或不必要的文本。
- 在 Markdown 中，通过添加示例的语言来指定代码块的类型。
```shell
...
- 将命令和输出内容拆分到不同的代码块中。
内嵌代码格式设置
- 对文件名、目录、路径和少量代码使用代码样式。
- 使用内嵌代码样式，不要使用斜体、“引号”或粗体。
- 是：
bazel help <command>：<command>的打印帮助和选项 - 否：bazel help command：输出“command”的帮助和选项
- 是：