文档风格指南
本风格指南改编自 Kubernetes 风格指南。
本页概述了 Harbor 文档的写作风格指南，您应该在编写或编辑内容时将其作为参考。这些是指导原则，而不是规则。在编写文档时请运用您的最佳判断，并随时提出对这些指南的更改建议。
风格指南的更改由 Harbor 维护者作为一个小组进行。要提出更改或添加，请创建 issue/PR，或参加 社区会议 讨论您的建议。
Harbor 文档使用 Goldmark Markdown 渲染器。
内容最佳实践
使用现在时
| 正面示例 | 反面示例 |
|---|---|
| 此命令启动一个代理。 | 此命令将启动一个代理。 |
例外：如果需要表达正确的含义，请使用将来时或过去时。
使用主动语态
| 正面示例 | 反面示例 |
|---|---|
| 您可以使用浏览器探索 API。 | API 可以使用浏览器进行探索。 |
| YAML 文件指定副本计数。 | 副本计数在 YAML 文件中指定。 |
例外：如果主动语态导致句子结构笨拙，请使用被动语态。
使用简单直接的语言
使用简单直接的语言。避免使用不必要的短语，例如说“请”。
| 正面示例 | 反面示例 |
|---|---|
| 要创建 ReplicaSet，… | 为了创建 ReplicaSet，… |
| 查看配置文件。 | 请查看配置文件。 |
| 查看 Pod。 | 使用下一个命令，我们将查看 Pod。 |
称呼读者为“您”
| 正面示例 | 反面示例 |
|---|---|
| 您可以通过…创建一个 Deployment。 | 我们将通过…创建一个 Deployment。 |
| 在前面的输出中，您可以看到… | 在前面的输出中，我们可以看到… |
避免使用拉丁语短语
优先使用英语术语而不是拉丁语缩写。
| 正面示例 | 反面示例 |
|---|---|
| 例如，… | 例如，… |
| 也就是说，… | 即，… |
例外：对 et cetera 使用“etc.”。
应避免的模式
避免使用“我们”
在句子中使用“我们”可能会造成混淆，因为读者可能不知道他们是否是您描述的“我们”的一部分。
| 正面示例 | 反面示例 |
|---|---|
| 版本 1.4 包括… | 在版本 1.4 中，我们添加了… |
| Kubernetes 提供了一个新功能用于… | 我们提供了一个新功能… |
| 本页教您如何使用 Pod。 | 在本页中，我们将学习关于 Pod 的知识。 |
避免使用行话和习语
许多读者以英语为第二语言。避免使用行话和习语，以帮助他们更好地理解。
| 正面示例 | 反面示例 |
|---|---|
| 在内部，… | 在底层，… |
| 创建一个新集群。 | 启动一个新的集群。 |
避免关于未来或很快会过时的陈述
避免做出承诺或暗示未来。如果您需要谈论 Beta 功能，请将文本放在标题下，以将其标识为 Beta 信息。
还要避免使用诸如“最近”、“当前”和“新”之类的词。今天的新功能可能在几个月后就不再被认为是新的了。
| 正面示例 | 反面示例 |
|---|---|
| 在版本 1.4 中，… | 在当前版本中，… |
| Federation 功能提供… | 新的 Federation 功能提供… |
语言
本文档使用美式英语拼写和语法。
文档格式标准
对占位符使用尖括号
对占位符使用尖括号。告诉读者占位符代表什么。
-
显示关于 Pod 的信息
kubectl describe pod <pod-name> -n <namespace>如果 Pod 在默认命名空间中，您可以省略 ‘-n’ 参数。
对用户界面元素使用粗体
| 正面示例 | 反面示例 |
|---|---|
| 单击 Fork。 | 单击 “Fork”。 |
| 选择 Other。 | 选择 “Other”。 |
对文件名、目录、路径、对象字段名称和命名空间使用代码样式
| 正面示例 | 反面示例 |
|---|---|
打开 envars.yaml 文件。 |
打开 envars.yaml 文件。 |
转到 /docs/tutorials 目录。 |
转到 /docs/tutorials 目录。 |
打开 /_data/concepts.yaml 文件。 |
打开 /_data/concepts.yaml 文件。 |
在引号内使用标点符号
| 正面示例 | 反面示例 |
|---|---|
| 事件记录时会带有一个关联的“stage”。 | 事件记录时会带有一个关联的“stage”。 |
| 副本被称为“fork”。 | 副本被称为“fork”。 |
例外：当引用的词是用户输入时。
示例
- 我的用户 ID 是 “IM47g”。
- 您尝试过密码 “mycatisawesome” 吗？
内联代码格式
对内联代码和命令使用代码样式
对于 HTML 文档中的内联代码，请使用 <code> 标签。在 Markdown 文档中，请使用反引号 (`)。
| 正面示例 | 反面示例 |
|---|---|
kubectl run 命令创建一个 Deployment。 |
“kubectl run” 命令创建一个 Deployment。 |
对于声明式管理，请使用 kubectl apply。 |
对于声明式管理，请使用 “kubectl apply”。 |
使用单反引号包围内联代码。例如，var example = true。 |
使用两个星号 (**) 或下划线 (_) 包围内联代码。例如，var example = true。 |
| 在多行代码块之前和之后使用三反引号 (```) 来创建围栏式代码块。 | 使用多行代码块来创建图表、流程图或其他插图。 |
| 使用具有上下文的有意义的变量名。 | 使用诸如 ‘foo’、‘bar’ 和 ‘baz’ 之类的变量名，这些名称没有意义且缺乏上下文。 |
| 删除代码中的尾随空格。 | 在代码中添加尾随空格（如果这些空格很重要），因为屏幕阅读器也会读出空格。 |
对字符串和整数类型的字段值使用普通样式
对于字符串或整数类型的字段值，请使用普通样式，不带引号。
| 正面示例 | 反面示例 |
|---|---|
将 imagePullPolicy 的值设置为 Always。 |
将 imagePullPolicy 的值设置为 “Always”。 |
将 image 的值设置为 nginx:1.16。 |
将 image 的值设置为 nginx:1.16。 |
将 replicas 字段的值设置为 2。 |
将 replicas 字段的值设置为 2。 |
代码片段格式
不要包含命令提示符
| 正面示例 | 反面示例 |
|---|---|
| kubectl get pods | $ kubectl get pods |
将命令与输出分开
验证 Pod 是否在您选择的节点上运行
kubectl get pods --output=wide
输出类似于这样
NAME READY STATUS RESTARTS AGE IP NODE
nginx 1/1 Running 0 13s 10.200.0.4 worker0
Harbor 词汇表
一个 Harbor 特有术语和词汇的列表，用于在整个站点中保持一致。
| 术语 | 用法 |
|---|---|
| Kubernetes | Kubernetes 应该始终大写。 |
| Harbor | Harbor 应该始终大写。 |
| Docker | Docker 应该始终大写。 |
| Allowlist | 使用 allowlist 而不是 whitelist。 |
| Denylist | 使用 denylist 而不是 blacklist。 |
Markdown 元素
标题
访问本文档的人员可能会使用屏幕阅读器或其他辅助技术 (AT)。屏幕阅读器 是线性输出设备，它们一次输出页面上的一个项目。如果页面上有很多内容，您可以使用标题为页面提供内部结构。良好的页面结构有助于所有读者轻松浏览页面或筛选感兴趣的主题。
| 正面示例 | 反面示例 |
|---|---|
| 在每个页面或博客文章中包含标题。 | 在一个页面中包含多个一级标题 (#)。 |
| 使用有序标题来提供内容有意义的高级大纲。 | 除非绝对必要，否则请使用 4 级到 6 级标题。如果您的内容如此详细，则可能需要将其分解为单独的文章。 |
| 对标题使用标题大小写。例如，Extend Kubectl With Plugins | 对标题使用句子大小写。例如，Extend kubectl with plugins |
段落
| 正面示例 | 反面示例 |
|---|---|
| 尽量将段落保持在 6 句话以下。 | 写冗长的段落。 |
使用三个连字符 (---) 创建水平线，用于段落内容中的分隔。 |
使用水平线进行装饰。 |
链接
| 正面示例 | 反面示例 |
|---|---|
| 编写超链接，使其为您提供链接内容的上下文。例如：您的机器上某些端口是开放的。请参阅 check required ports 了解更多详情。 | 使用含糊不清的术语，例如“点击这里”。例如：您的机器上某些端口是开放的。请点击 这里 了解更多详情。 |
编写 Markdown 样式的链接：[链接文本](URL)。例如：[community meeting agenda](https://hackmd.io/Jq6F5zqZR7S80CeDWUklkA)，输出为 community meeting agenda。 |
编写 HTML 样式的链接：<a href="/media/examples/link-element-example.css" target="_blank">访问我们的教程！</a> |
列表
将列表中彼此相关且需要按特定顺序出现或指示多个项目之间关联的项目分组。当屏幕阅读器遇到列表时（无论是有序列表还是无序列表），它都会向用户宣布存在一组列表项。然后，用户可以使用箭头键在列表中的各个项目之间上下移动。网站导航链接也可以标记为列表项；毕竟它们只不过是一组相关链接。
-
如果列表中的一个或多个项目是完整的句子，则在列表中的每个项目末尾加句点。为了保持一致性，通常所有项目或所有项目都不应是完整的句子。
-
作为不完整介绍性句子一部分的有序列表可以小写，并且标点符号的处理方式就好像每个项目都是介绍性句子的一部分一样。
-
对于有序列表，请使用数字一 (
1.)。 -
对于无序列表，请使用 (+)、(*)、或 (-)，在同一文档中保持一致。
-
在每个列表后留一个空行。
-
用四个空格缩进嵌套列表（例如，⋅⋅⋅⋅）。
-
列表项可以包含多个段落。列表项中的每个后续段落都必须缩进四个空格或一个制表符。
表格
数据表的语义目的是呈现表格数据。有视觉的用户可以快速扫描表格，但屏幕阅读器会逐行浏览。表格 标题 用于为数据表创建描述性标题。辅助技术 (AT) 使用 HTML 表格标题元素来向用户标识页面结构中的表格内容。
如果您需要创建表格，请在 markdown 中创建表格，并使用表格 Hugo shortcode 来包含标题。
{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}
注意： 此 shortcode 不支持 markdown 引用样式链接。在表格中使用内联样式链接。请参阅有关 markdown 链接样式 的更多信息。
在本页
贡献