感谢您为 Bazel 文档做出贡献。这是一份可帮助您快速入门的文档样式指南。如果本指南未能解答您的任何样式问题，请参阅 Google 开发者文档样式指南。
定义原则
Bazel 文档应遵循以下原则：
- 简洁。尽可能使用尽可能少的字词。
- 清除：使用通俗易懂的语言。使用简单易懂的语言，使其适合五年级学生的阅读水平。
- 一致。在整个文档中，对于重复的概念，请使用相同的字词或短语。
- 正确。撰写内容时，请避免使用基于时间的信息和对未来的承诺，从而尽可能确保内容正确。
写作
本部分包含基本写作技巧。
标题
- 页面级标题从 H2 开始。（H1 标题用作网页标题）。
尽可能简短地设置标题。这样，它们就能放在目录下，而无需换行。
- 是：权限
- 否：关于权限的简要说明
对标题采用句首字母大写形式
- 是：设置工作区
- 否：设置工作区
尽量让标题与任务相关或具有实用价值。如果标题是概念性的，则可能基于理解，但要写出用户执行的操作。
- 是：保留图表顺序
- 否：关于图表顺序的保留
名称
将专有名词（例如 Bazel 和 Starlark）的首字母大写。
- 是：在构建结束时，Bazel 会输出请求的目标。
- 否：构建结束时，bazel 将输出请求的目标。
保持一致。不要为现有概念引入新名称。在适用的情况下，请使用术语库中定义的术语。
- 例如，如果您要介绍如何在终端上发出命令，请勿在同一页面上同时使用“终端”和“命令行”字样。
页面范围
每个网页都应有一个用途，并且应在开始时定义该用途。这有助于读者更快地找到所需内容。
- 是：本页介绍了如何在 Windows 上安装 Bazel。
- 否：（无开场白。）
在页面底部，告知读者下一步该怎么做。对于没有明确操作的网页，您可以添加指向类似概念、示例或其他探索途径的链接。
主题
在 Bazel 文档中，读者应该主要为用户，即使用 Bazel 构建软件的用户。
将读者称为“您”。（如果由于某种原因您无法使用“您”，请使用中性语言，例如。）
- 是：如需使用 Bazel 构建 Java 代码，您必须安装 JDK。
- MAYBE：要使用 Bazel 构建 Java 代码，用户必须安装 JDK。
- 否：用户必须安装 JDK，才能使用 Bazel 构建 Java 代码。
如果您的受众群体不是一般 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 启动，之后将使用输出构建 Y。
语气
以适合企业的语气撰写内容。
避免使用口语化的语言。翻译仅限英语的短语会更难。
- 是：规则集良好
- 否：那么什么是良好的规则集？
避免使用过于正式的语言。在撰写时，请假设您要向对技术感兴趣但不了解细节的用户说明相关概念。
格式设置
文件类型
为了便于阅读，请在 80 个字符处换行。长链接或代码段可以更长，但应从新行开始。例如：
链接
使用描述性的链接文字，而不是“此处”或“在下方”。这样做有助于更轻松地浏览文档，也更适合屏幕阅读器。
- 是：如需了解详情，请参阅 [安装 Bazel]。
- 否：如需了解详情，请参阅 [此处]。
如果可能，请在句子结尾处添加链接。
- 是：如需了解详情，请参阅 [link]。
- 否：如需了解详情，请参阅 [link]。
列表
- 使用有序列表描述如何通过步骤完成任务
- 使用无序列表列出非基于任务的内容。（仍应有排序顺序，例如按字母顺序、重要性等排序）
- 采用并行结构进行编写。例如：
- 将所有列表项都改为句子。
- 先从同种时态的动词开始。
- 如果有步骤需要遵循，请使用有序列表。
占位符
使用尖括号表示用户应更改的变量。在 Markdown 中，请使用反斜杠转义尖括号：
\<example\>。- 是：
bazel help <command>：输出<command>的帮助和选项 - 否：bazel help command：输出“command”的帮助和选项
- 是：
对于复杂的代码示例，请使用在上下文中有意义的占位符。
目录
使用网站支持的自动生成的目录。请勿添加手动目录。
代码
代码示例是开发者的好帮手。您可能已经知道如何编写这些代码，但下面还是提供了一些提示。
如果您要引用一小段代码，可以将其嵌入到句子中。如果您希望读者使用代码（例如复制命令），请使用代码块。
代码块
- 内容要简短。从代码示例中消除所有多余或不必要的文字。
- 在 Markdown 中，通过添加示例的语言来指定代码块的类型。
```shell
...
- 将命令和输出分隔到不同的代码块中。
内嵌代码格式设置
- 对文件名、目录、路径和小段代码使用代码样式。
- 使用内嵌代码样式，而不是斜体、“引号”或bolding。
- 是：
bazel help <command>：打印<command>的帮助和选项 - 否：bazel help command：输出“command”的帮助和选项
- 是：