感谢您为 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]。
- 否:如需了解详情,请参阅 [链接]。
列表
- 使用有序列表描述如何通过步骤完成任务
- 使用无序列表列出并非基于任务的内容。(应该仍存在某种排序顺序,例如按字母顺序、重要性等)。
- 采用并行结构进行写入。例如:
- 将所有清单项设为句子。
- 先从时态相同的动词开始。
- 如果有步骤,请使用有序列表。
占位符
尖括号用于表示用户应更改的变量。在 Markdown 中,使用反斜杠对尖括号进行转义:
\<example\>
。- 是:
bazel help <command>
:输出<command>
的帮助和选项 - 否:bazel help command:用于输出“command”的帮助和选项
- 是:
尤其是对于复杂的代码示例,请使用在上下文中有意义的占位符。
目录
使用该网站支持的自动生成的 TOC。请勿添加手动 TOC。
编码
代码示例是开发者最好的帮手。您可能已经知道如何编写这些代码,但下面提供了一些提示。
如果您要引用一小段代码,则可以将其嵌入到句子中。如果您希望读者使用该代码(例如复制命令),请使用代码块。
代码块
- 尽量简短。消除代码示例中的所有冗余或不必要的文本。
- 在 Markdown 中,通过添加示例语言来指定代码块的类型。
```shell
...
- 将命令和输出分离到不同的代码块中。
内嵌代码格式
- 对文件名、目录、路径和少量代码使用代码样式。
- 使用内嵌代码样式设置(而非斜体、“引号”或粗体)。
- 是:
bazel help <command>
:输出<command>
的帮助和选项 - 否:bazel help command:用于输出“command”的帮助和选项
- 是: