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