文档风格指南
本风格指南适用于 Kubeflow 文档。本风格指南帮助贡献者编写读者能够快速准确理解的文档。
Kubeflow 文档旨在实现以下目标：
- 风格和术语一致，以便读者能够预期某些结构和惯例。读者不必反复学习如何使用文档或质疑他们是否正确理解了某些内容。
- 文字清晰、简洁，以便读者能够快速找到并理解他们所需的信息。
使用标准的美国拼写
使用美国拼写，而不是英联邦或英国拼写。请参考《韦氏大学词典第十一版》（Merriam-Webster’s Collegiate Dictionary, Eleventh Edition）。
谨慎使用大写字母
一些提示
- 页面内每个标题仅首字母大写。（即使用句子大小写。）
- 页面标题中（几乎）每个单词的首字母大写。（即使用标题大小写。）“and”、“in”等小词不首字母大写。
- 页面内容中，仅品牌名称首字母大写，例如 Kubeflow、Kubernetes 等等。关于品牌名称的更多信息，请参阅下文。
- 不要使用大写字母来强调单词。
首次使用缩写词和首字母缩略词时，写出全称
首次在页面上使用任何缩写词或首字母缩略词时，务必写出全称。不要假设人们知道缩写词或首字母缩略词的含义，即使它们看起来是常识。
示例：“要在本地虚拟机 (VM) 中运行 Kubernetes”
如果需要，可以使用缩写形式
例如，可以使用“it’s”而不是“it is”。
使用完整、正确的品牌名称
提及产品或品牌时，请使用全称。按照产品所有者在产品文档中的方式大写名称。即使缩写被广泛使用，也不要使用，除非产品所有者批准了该缩写。
| 使用这个 | 而不是这个 |
|---|---|
| Kubeflow | kubeflow |
| Kubernetes | k8s |
| ksonnet | Ksonnet |
保持标点符号一致
页面内的标点符号使用要保持一致。例如，如果您在列表中的每个项目后面都使用句号，那么该页面的所有其他列表也都要使用句号。
如果您不确定某个特定惯例，请查看其他页面。
示例
- Kubeflow 文档的大多数页面在每个列表项的末尾都使用句号。
- 页面副标题末尾不使用句号，且副标题不必是完整的句子。（副标题来自页面前置信息 (front matter) 中的
description字段。）
使用主动语态而不是被动语态
被动语态通常令人困惑，因为它不清楚谁应该执行该动作。
| 使用主动语态 | 而不是被动语态 |
|---|---|
| 您可以配置 Kubeflow 以 | Kubeflow 可以被配置以 |
| 将目录添加到您的 path 中 | 该目录应该被添加到您的 path 中 |
使用一般现在时
避免使用将来时（“will”）以及虚拟语气等复杂语法（“would”、“should”）。
| 使用一般现在时 | 代替将来时或复杂语法 |
|---|---|
| 以下命令将预置一个虚拟机 | 以下命令将会预置一个虚拟机 |
| 如果您添加此配置元素，系统将对互联网开放 | 如果您添加此配置元素，系统将会对互联网开放 |
例外：如果需要传达正确含义，请使用将来时。这种情况很少见。
直接称呼读者
在句子中使用“我们”可能会令人困惑，因为读者可能不知道他们是否是您描述的“我们”的一部分。
例如，比较以下两个句子
- “在此版本中，我们添加了许多新功能。”
- “在本教程中，我们构建了一个飞碟。”
“开发者”或“用户”等词语可能含糊不清。例如，如果读者正在构建一个也有用户的产品，那么读者不知道您是指读者本人还是其产品的用户。
| 直接称呼读者 | 而不是“我们”、“用户”或“开发者” |
|---|---|
| 将目录包含在您的 path 中 | 用户必须确保目录已包含在他们的 path 中 |
| 在本教程中，您将构建一个飞碟 | 在本教程中，我们构建一个飞碟 |
使用简短、简单的句子
保持句子简短。短句子比长句子更容易阅读。以下是一些编写短句子的技巧。
| 使用更少的词语来表达相同的意思，而不是许多词语 | |
|---|---|
| 使用这个 | 而不是这个 |
| 您可以使用 | 也可以使用 |
| 您可以 | 您能够 |
| 将一个长句拆分成两个或多个短句 | |
|---|---|
| 使用这个 | 而不是这个 |
| 您不需要一个正在运行的 GKE 集群。部署过程会为您创建一个集群。 | 您不需要一个正在运行的 GKE 集群，因为部署过程会为您创建一个集群。 |
| 使用列表代替一个显示各种选项的长句 | |
|---|---|
| 使用这个 | 而不是这个 |
要训练模型
| 要训练模型，您必须将您的程序打包到 Kubernetes 容器中，将容器上传到在线仓库，然后提交您的训练 Job。 |
避免过多的文本样式
提及 UI 控件或其他 UI 元素时，使用粗体文本。
使用代码样式来表示：
- 文件名、目录和路径
- 内联代码和命令
- 对象字段名称
避免使用粗体文本或大写字母进行强调。如果页面上有过多的文本高亮，会变得令人困惑甚至恼火。
占位符使用尖括号
例如
export KUBEFLOW_USERNAME=<您的用户名>--email <您的邮箱地址>
为图片设置样式
Kubeflow 文档识别 Bootstrap 类来样式化图片和其他内容。
以下代码片段展示了使图片在页面上美观显示的典型样式：
<!-- for wide images -->
<img src="/docs/images/my-image.png"
alt="My image"
class="mt-3 mb-3 border rounded">
<!-- for tall images -->
<img src="/docs/images/my-image.png"
alt="My image"
class="mt-3 mb-3 border rounded"
style="width: 100%; max-width: 30em">
要查看带样式的图片示例，请参阅OAuth 设置页面。
有关更多帮助，请参阅 Bootstrap 图片样式指南和 Bootstrap 实用工具，例如边框。
详细的风格指南
《Google 开发者文档风格指南》（Google Developer Documentation Style Guide）包含有关为开发者受众编写清晰、可读、简洁文档的特定方面的详细信息。
下一步
- 请参阅文档 README，了解有关贡献 Kubeflow 文档的指导。