Bazel 文档样式指南

报告问题 查看源代码

感谢您为 Bazel 的文档贡献代码。这可作为一份快速文档样式指南,助您快速上手。对于本指南未解答的任何样式问题,请遵循 Google 开发者文档样式指南

定义原则

Bazel 文档应遵循以下原则:

  • 简洁。使用尽可能简短的字词。
  • 清除:请使用简单明了的语言。提供五年级阅读水平时不加行话。
  • 一致。在整个文档中使用相同的概念或短语重复概念。
  • 正确。撰写内容时,避免基于时间的信息和在未来承诺,确保内容尽可能正确。

写作

本部分包含基本的撰写提示。

标题

  • 网页级标题从 H2 开始。(H1 标题用作网页标题。)
  • 请尽量合理使用标题。这样一来,它们无需换行也能适应 TOC。

    • :权限
    • :有关权限的简短说明
  • 标题采用句首字母大写形式

    • :设置您的工作区
    • :设置您的工作区
  • 尽量让标题具有实用性或可操作。如果标题是概念性的,这可能基于理解,但应写入用户执行的操作。

    • :保留图表顺序
    • :关于保存图表顺序

名称

  • 将专有名词大写,例如 Bazel 和 Starlark。

    • :在构建结束时,Bazel 会输出请求的目标。
    • :在构建结束时,bazel 会输出请求的目标。
  • 请保持一致。不要为现有概念引入新名称。在适用的情况下,请使用术语库中定义的术语。

    • 例如,如果您要撰写有关在终端上发出命令的信息,请勿在该网页上同时使用终端和命令行。

页面范围

  • 每个网页都应该有一个用途,并且应在开始时加以定义。这有助于读者更快地找到所需内容。

    • :本页面介绍了如何在 Windows 上安装 Bazel。
    • :(无介绍性句子。)
  • 在页面底部,告知读者接下来要执行的操作。对于没有明确操作的网页,您可以添加指向类似概念、示例或其他探索途径的链接。

主题

在 Bazel 文档中,受众群体应该主要是用户,即使用 Bazel 构建软件的用户。

  • 使用“您”来称呼读者,(如果由于某种原因您无法使用“您”,请使用中性语言,例如。)

    • :如需使用 Bazel 构建 Java 代码,您必须安装 JDK。
    • MAYBE:如果用户要使用 Bazel 构建 Java 代码,他们必须安装 JDK。
    • :如需使用 Bazel 构建 Java 代码,他/她必须安装 JDK。
  • 如果您的受众群体不是一般的 Bazel 用户,请在网页开头或相应部分中定义受众群体。其他受众群体可能包括维护者、贡献者、迁移者或其他角色。

  • 避免使用“我们”。用户文档中没有作者,只是告诉人们可能发生的情况。

    • :随着 Bazel 的演变,您应更新代码库以保持兼容性。
    • :Bazel 不断发展演变,我们将对 Bazel 进行更改,有时不兼容,并且需要 Bazel 用户做出一些更改。

时间

尽可能避免使用会让事情有时间依据的字词,例如提及具体日期(2022 年第 2 季度)或说出“now”、“now”或“on-on”。这些设置很快就会过时,如果它是未来的预测,则可能会不正确。请改为指定版本级别,例如“Bazel X.x 及更高版本支持 <feature>”或 GitHub 问题链接。

  • :Bazel 0.10.0 或更高版本支持远程缓存。
  • :Bazel 不久后(可能在 2017 年 10 月)就会支持远程缓存。

时态

  • 使用现在时。除非绝对有必要,否则请避免使用过去或将来的时态。

    • :Bazel 在发现不符合此规则的依赖项时会发出错误。
    • :如果 Bazel 发现有不符合此规则的依赖项,就会发出错误。
  • 尽可能使用主动语态(对象对物体进行操作时)而不是被动语态(对象对物体做出动作时)。一般而言,主动语态使句子更清晰,因为它显示了谁是责任人。如果使用主动语态,会分散注意力,请使用被动语态。

    • :Bazel 会启动 X,并使用输出来构建 Y。
    • :X 由 Bazel 启动,之后将使用输出构建 Y。

基调

撰写文案利于商务。

  • 避免使用口语化的语言。只翻译英语的短语更难

    • :良好的规则集
    • :什么是良好的规则集?
  • 避免使用过于正式的语言。请像想了解技术知识但不知道详细信息的人一样 解释各种概念。

格式设置

文件类型

为确保可读性,请在第 80 个字符处换行。较长的链接或代码段可能更长,但应另起一行。例如:

  • 请使用描述性链接文字,不要使用“此处”或“下方”。这种做法可让您更轻松地扫描文档,并且更适合屏幕阅读器。

    • :如需了解详情,请参阅 [安装 Bazel]。
    • :如需了解详情,请参阅 [此处]。
  • 请尽可能以链接结尾。

    • :如需了解详情,请参阅 [link]。
    • :如需了解详情,请参阅 [链接]。

列表

  • 使用有序列表描述如何通过步骤完成任务
  • 使用无序列表列出并非基于任务的内容。(应该仍存在某种排序顺序,例如按字母顺序、重要性等)。
  • 采用并行结构进行写入。例如:
    1. 将所有清单项设为句子。
    2. 先从时态相同的动词开始。
    3. 如果有步骤,请使用有序列表。

占位符

  • 尖括号用于表示用户应更改的变量。在 Markdown 中,使用反斜杠对尖括号进行转义:\<example\>

    • bazel help <command>:输出 <command> 的帮助和选项
    • :bazel help command:用于输出“command”的帮助和选项
  • 尤其是对于复杂的代码示例,请使用在上下文中有意义的占位符。

目录

使用该网站支持的自动生成的 TOC。请勿添加手动 TOC。

编码

代码示例是开发者最好的帮手。您可能已经知道如何编写这些代码,但下面提供了一些提示。

如果您要引用一小段代码,则可以将其嵌入到句子中。如果您希望读者使用该代码(例如复制命令),请使用代码块。

代码块

  • 尽量简短。消除代码示例中的所有冗余或不必要的文本。
  • 在 Markdown 中,通过添加示例语言来指定代码块的类型。
```shell
...
  • 将命令和输出分离到不同的代码块中。

内嵌代码格式

  • 对文件名、目录、路径和少量代码使用代码样式。
  • 使用内嵌代码样式设置(而非斜体、“引号”或粗体)。
    • bazel help <command>:输出 <command> 的帮助和选项
    • :bazel help command:用于输出“command”的帮助和选项