Bazel 文档样式指南

<ph type="x-smartling-placeholder"></ph> 报告问题 查看来源 敬上 每晚 · 7.3。 · 7.2 条 · 7.1。 · 7.0。 · 6.5

感谢您为 Bazel 的文档贡献力量。它可快速 文档样式指南。对于任何风格问题, 请按照 Google 开发者文档样式指南

定义原则

Bazel 文档应坚持以下原则:

  • 简洁。使用尽可能少的字词。
  • 清除 -使用通俗易懂的语言。写五年级学生必备应用,不使用行话 阅读水平
  • 一致。对重复的概念使用相同的字词或词组 。
  • 正确。请采用适当的撰写方式,确保内容始终正确 避免基于时间的信息和对未来的承诺。

写作

本部分包含基本写作技巧。

标题

  • 页面级标题从 H2 开始。(H1 标题用作网页标题)。
  • 尽可能缩短标题。这样,它们就可以在目录下 无需换行

    • :权限
    • :简要说明权限
  • 将句首字母大写作为标题

    • :已设置工作区
    • :设置工作区
  • 尽量让标题与任务相关或具有实用价值。如果标题是概念性的, 它可以基于用户的理解,但会根据用户的行为而撰写。

    • :保留图表顺序
    • :保留图表顺序

名称

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

    • :构建结束时,Bazel 会输出请求的目标。
    • :构建结束时,bazel 将输出请求的目标。
  • 保持一致。不要为现有概念引入新名称。地点 请使用 术语库

    • 例如,如果您要编写有关在 终端,请勿在页面上同时使用终端和命令行。

页面范围

  • 每个页面都应该有一个用途,并在 开头。这有助于读者更快地找到所需内容。

    • :本页介绍了如何在 Windows 上安装 Bazel。
    • :(没有介绍性语句。)
  • 在页面底部,告诉读者接下来该怎么做。对于 没有明确的操作,可以添加指向类似概念的链接, 或其他探索途径。

主题

在 Bazel 文档中,目标对象应主要是用户,即使用 使用 Bazel 构建软件

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

    • :要使用 Bazel 构建 Java 代码,请执行以下操作: 必须安装 JDK
    • MAYBE:要使用 Bazel 构建 Java 代码,用户必须安装 JDK。
    • :如果用户需要使用 Bazel,他/她必须安装 JDK。
  • 如果您的受众群体不是常规 Bazel 用户,请在 。其他受众群体可能包括 维护者、贡献者、迁移者或其他角色。

  • 避免使用“我们”。用户文档中没有作者;告诉大家

    • 需要:随着 Bazel 的发展,您应该更新代码库以维护 兼容性。
    • 不能:Bazel 不断演变,我们会在 时间不兼容,并且需要 Bazel 用户进行一些更改。

时间

尽可能避免使用会及时指示事物的字词,例如 具体日期(2022 年第 2 季度)或是“现在”“目前”或“马上”。这些 很快就会过时,如果是未来的预测,则可能是错误的。相反, 而应指定版本级别,例如“Bazel X.x 及更高版本支持 &lt;feature&gt;或 GitHub 问题链接。

  • :Bazel 0.10.0 或更高版本支持 远程缓存
  • :Bazel 即将支持远程访问 可能会在 2017 年 10 月推出。

时态

  • 使用现在时。除非绝对必要,否则避免使用过去或未来时态 为清晰起见。

    • :Bazel 会在出错时发出错误 查找不符合此规则的依赖项。
    • :如果 Bazel 发现了 则 Bazel 会发出错误。
  • 尽可能使用主动语态(即主语对物体做出动作),而不是 被动语态(主语对宾语做出动作)。一般来说, 主动语态可以使句子更加清晰,因为它表明了谁是责任人。如果 使用主动语态会降低清晰度,请使用被动语态。

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

语气

以适合企业的语气撰写内容。

  • 避免使用口语化的语言。较难翻译包含 只有英文版。

    • :规则集良好
    • :什么是好的规则集?
  • 避免使用过于正式的语言。撰写时要像是在解释 向对技术感兴趣,但不了解细节的人。

格式设置

文件类型

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

  • 使用描述性的链接文字,而不是“此处”或“低于”的值。这种做法 更易于扫描文档,更适合屏幕阅读器。

    • :如需了解详情,请参阅 [安装 Bazel]。
    • :如需了解详情,请参阅 [此处]。
  • 如果可能,请在句子的结尾加上链接。

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

列表

  • 使用有序列表描述如何完成带有步骤的任务
  • 使用无序列表列出非基于任务的内容。(其中应该有 仍遵循排序顺序,例如按字母顺序、重要性等)。
  • 采用并行结构进行编写。例如:
    1. 让所有列表项成为句子。
    2. 从具有相同时态的动词开始。
    3. 如果还要遵循相应步骤,请使用有序列表。

占位符

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

    • bazel help <command>:打印版 “<command>”的帮助和选项
    • :bazel help command:打印帮助 以及“命令”选项
  • 尤其是对于复杂的代码示例,请使用合适的占位符 结合上下文。

目录

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

代码

代码示例由开发者最好的朋友。你可能知道如何编写这些代码 但下面是几点提示

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

代码块

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

内嵌代码格式

  • 对文件名、目录、路径和少量代码使用代码样式。
  • 使用内嵌代码样式,而不要使用“斜体”“引号”粗体
    • bazel help <command>:打印版 “<command>”的帮助和选项
    • :bazel help command:打印帮助 以及“命令”选项