感谢您为 Bazel 的文档贡献力量。这是一份可帮助您快速入门的文档样式指南。对于本指南未解答的任何样式问题,请参阅 Google 开发者文档样式指南。
定义原则
Bazel 文档应坚持以下原则:
- 简洁。使用尽可能少的字词。
- 清除 -使用通俗易懂的语言。对于五年级的阅读水平来说,写作时不要使用行话。
- 一致。在整个文档中,对于重复的概念,请使用相同的字词或词组。
- 正确。撰写内容时,请避免使用基于时间的信息和对未来的承诺,从而尽可能确保内容正确。
编写
本部分包含基本写作技巧。
标题
- 页面级标题从 H2 开始。(H1 标题用作网页标题)。
尽可能缩短标题。这样,它们就能放入目录,而无需换行。
- 是:权限
- 否:简要说明权限
将句首字母大写作为标题
- 是:已设置工作区
- 否:设置工作区
尽量让标题与任务相关或具有实用价值。如果标题是概念性的,则可以基于理解而撰写,但应描述用户的行为。
- 是:保留图表顺序
- 否:保留图表顺序
姓名
将专有名词大写,例如 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 季度)或提及“现在”“目前”或“即将”。这些信息很快就会过时,如果是未来预测,则可能是错误的。请改为指定版本级别,例如“Bazel X.x 及更高版本支持 <feature>”或 GitHub 问题链接。
- 是:Bazel 0.10.0 或更高版本支持远程缓存。
- 否:Bazel 很快将支持远程缓存,并可能从 2017 年 10 月开始。
时态
使用现在时。除非绝对必要,否则请避免使用过去时或将来时。
- 是:如果 Bazel 发现不符合此规则的依赖项,则会发出错误。
- 否:如果 Bazel 发现了不符合此规则的依赖项,则 Bazel 会发出错误。
尽可能使用主动语态(主语对物体做出动作)而不是被动语态(主语对物体做出动作)。通常,主动语态可让句子更清晰,因为它表明了谁是负责人员。如果使用主动语态会降低清晰度,请使用被动语态。
- 是:Bazel 启动 X 并使用输出构建 Y。
- 否:X 由 Bazel 启动,之后将使用输出构建 Y。
风格
以适合企业的语气撰写内容。
避免使用口语化的语言。翻译特定于英语的短语更难。
- 是:规则集良好
- 否:什么是好的规则集?
避免使用过于正式的语言。在撰写文案时,假装是在向对技术好奇的人解释概念,但不了解细节。
格式设置
文件类型
为确保可读性,请在 80 个字符处换行。长链接或代码段可能更长,但应另起一行。例如:
链接
使用描述性的链接文字,而不是“此处”或“在下方”。这种做法更易于扫描文档,更适合屏幕阅读器。
- 是:如需了解详情,请参阅 [安装 Bazel]。
- 否:如需了解详情,请参阅 [此处]。
如果可能,请在句子的结尾加上链接。
- 是:如需了解详情,请参阅 [link]。
- 否:请访问 [link] 了解详情。
列表
- 使用有序列表描述如何完成带有步骤的任务
- 使用无序列表列出非基于任务的内容。(仍应按字母顺序、重要性等排序。)
- 采用并行结构进行编写。例如:
- 让所有列表项成为句子。
- 从具有相同时态的动词开始。
- 如果还要遵循相应步骤,请使用有序列表。
占位符
使用尖括号表示用户应更改的变量。 在 Markdown 中,使用反斜杠对尖括号进行转义:
\<example\>
。- 是:
bazel help <command>
:打印<command>
的帮助和选项 - 否:bazel help command:输出“command”的帮助和选项
- 是:
请使用适合上下文的占位符,尤其是对于复杂的代码示例。
目录
使用网站支持的自动生成的目录。请勿添加手动目录。
代码
代码示例是开发者的得力助手。您可能已经知道如何编写这些代码,以下是几条提示。
如果您要引用一小段代码,可以将其嵌入句子中。 如果您希望读取器使用代码(例如复制命令),请使用代码块。
代码块
- 简明扼要。消除代码示例中的所有冗余或不必要的文本。
- 在 Markdown 中,通过添加示例的语言来指定代码块的类型。
```shell
...
- 将命令和输出拆分到不同的代码块中。
内嵌代码格式
- 对文件名、目录、路径和少量代码使用代码样式。
- 使用内嵌代码样式,而不要使用斜体、“引号”或粗体。
- 是:
bazel help <command>
:打印<command>
的帮助和选项 - 否:bazel help command:输出“command”的帮助和选项
- 是: