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