mirror of https://github.com/istio/istio.io.git
[zh] improve style-guide terminology (#14231)
Signed-off-by: xin.li <xin.li@daocloud.io>
This commit is contained in:
my-git9
GitHub
parent
86ca9f3eea
commit
8927a5e852
|
|
@ -8,25 +8,30 @@ aliases:
|
|||
keywords: [contribute]
|
||||
---
|
||||
|
||||
Istio 文档所有的内容都必须 **清晰明了** 且 **易于理解**。我们根据 Google 开发者风格指南中的[重点](https://developers.google.com/style/highlights)和[通则](https://developers.google.com/style/tone)定义了标准。关于您贡献的内容是如何被审核、接受的，请参见[审核页面](/zh/about/contribute/review)获取详情。
|
||||
Istio 文档所有的内容都必须**清晰明了**且**易于理解**。我们根据 Google
|
||||
开发者风格指南中的[重点](https://developers.google.com/style/highlights)和
|
||||
[通则](https://developers.google.com/style/tone)定义了标准。
|
||||
关于您贡献的内容是如何被审核、接受的，请参见[审核页面](/zh/about/contribute/review)获取详情。
|
||||
|
||||
您可以在此通过 Istio 特有的示例，找到 Istio 遵循的基本风格与实践指南的所有场景。
|
||||
|
||||
## 标题句首字母大写{#use-sentence-case-for-headings}
|
||||
## 标题句首字母大写 {#use-sentence-case-for-headings}
|
||||
|
||||
在您的文档中，为标题使用句首字母大写。即：仅将标题中第一个单词的首字母大写，专有名词或缩写除外。
|
||||
在您的文档中，为标题使用句首字母大写。即：仅将标题中第一个单词的首字母大写，
|
||||
专有名词或缩写除外。
|
||||
|
||||
| 正确做法 | 错误做法
|
||||
|------------------------|-----
|
||||
|Configuring rate limits | Configuring Rate Limits
|
||||
|Using Envoy for ingress | Using envoy for ingress
|
||||
|Using HTTPS | Using https
|
||||
|------------------------------|-----
|
||||
|Configuring rate limits | Configuring Rate Limits
|
||||
|Using Envoy for ingress | Using envoy for ingress
|
||||
|Using HTTPS | Using https
|
||||
|
||||
## front-matter 中 `title:` 字段的值使用首字母大写{#use-title-case-for-the-value-of-the-title-field-of-the-front-matter}
|
||||
## front-matter 中 `title:` 字段的值使用首字母大写 {#use-title-case-for-the-value-of-the-title-field-of-the-front-matter}
|
||||
|
||||
front-matter 中 `title:` 字段的文本必须使用首字母大小写。即：除连词和介词外，将每个单词的首字母大写。
|
||||
front-matter 中 `title:` 字段的文本必须使用首字母大小写。即：
|
||||
除连词和介词外，将每个单词的首字母大写。
|
||||
|
||||
## 使用现在时{#use-present-tense}
|
||||
## 使用现在时 {#use-present-tense}
|
||||
|
||||
| 正确做法 | 错误做法
|
||||
|-----------------------------|------
|
||||
|
|
@ -34,16 +39,16 @@ front-matter 中 `title:` 字段的文本必须使用首字母大小写。即：
|
|||
|
||||
例外：确实需要通过使用将来时或过去时才能表达正确的含义时。这种例外极为罕见，应尽可能的避免。
|
||||
|
||||
## 使用主动句式{#use-active-voice}
|
||||
## 使用主动句式 {#use-active-voice}
|
||||
|
||||
| 正确做法 | 错误做法
|
||||
|-------------------------------------------|------
|
||||
| 您可以使用浏览器查询API。 | API可以使用浏览器被查询。
|
||||
| YAML 指定了副本数量。 | 副本数量已被 YAML 指定。
|
||||
|
||||
## 使用简单直接的语言{#use-simple-and-direct-language}
|
||||
## 使用简单直接的语言 {#use-simple-and-direct-language}
|
||||
|
||||
使用简单直接的语言。避免使用不必要的短语，例如：“please”。
|
||||
使用简单直接的语言。避免使用不必要的短语，例如："please"。
|
||||
|
||||
| 正确做法 | 错误做法
|
||||
|----------------------------|------
|
||||
|
|
@ -51,48 +56,48 @@ front-matter 中 `title:` 字段的文本必须使用首字母大小写。即：
|
|||
|参见配置文件。 | 请参见配置文件。
|
||||
|查看 Pod。 | 通过下一个命令，可查看 Pod。
|
||||
|
||||
## 使用“您”称呼读者{#address-the-reader-as-you}
|
||||
## 使用"您"称呼读者 {#address-the-reader-as-you}
|
||||
|
||||
| 正确做法 | 错误做法
|
||||
|---------------------------------------|------
|
||||
| 您可以通过 …… 创建 `Deployment` | 我们将通过 …… 创建 `Deployment`
|
||||
| 在前面的输出中，您可以看到…… | 在前面的输出中，我们可以看到……
|
||||
| 您可以通过 ... 创建 `Deployment` | 我们将通过 ... 创建 `Deployment`
|
||||
| 在前面的输出中，您可以看到 ... | 在前面的输出中，我们可以看到 ...
|
||||
|
||||
## 创建语义清晰的链接{#create-useful-links}
|
||||
## 创建语义清晰的链接 {#create-useful-links}
|
||||
|
||||
链接有语义清晰也有不是最佳做法的。如：在 *此处* 或 *单击此处* 打开链接的常见做法就是不好的链接示例。
|
||||
链接有语义清晰也有不是最佳做法的。如：在**此处**或**单击此处**打开链接的常见做法就是不好的链接示例。
|
||||
请查看[这篇出色的文章](https://medium.com/@heyoka/dont-use-click-here-f32f445d1021)，
|
||||
其中解释了什么是好的超链接，并在创建或查看网站内容时牢记这些准则。
|
||||
|
||||
## 避免使用“我们”{#avoid-using-we}
|
||||
## 避免使用"我们" {#avoid-using-we}
|
||||
|
||||
在句子中使用“我们”可能会造成混淆，因为读者可能不知道他们是否属于您所描述的“我们”。
|
||||
在句子中使用“我们”可能会造成混淆，因为读者可能不知道他们是否属于您所描述的"我们"。
|
||||
|
||||
| 正确做法 | 错误做法
|
||||
|------------------------------------------|------
|
||||
| 1.4 版本中包括… | 在 1.4 版本中，我们添加了…
|
||||
| Istio 为 … 提供了一项新功能。 | 我们提供了一个新功能……
|
||||
| 1.4 版本中包括 ... | 在 1.4 版本中，我们添加了 ...
|
||||
| Istio 为 ... 提供了一项新功能。 | 我们提供了一个新功能 ...
|
||||
| 该页面教您如何使用 Pod。 | 在此页面中，我们将学习 Pod。
|
||||
|
||||
## 避免俚语和方言{#avoid-jargon-and-idioms}
|
||||
## 避免俚语和方言 {#avoid-jargon-and-idioms}
|
||||
|
||||
一些读者的母语不是英语，避免使用术语和习惯用语，可用以帮助他们更轻松的理解。
|
||||
|
||||
| 正确做法 | 错误做法
|
||||
| 正确做法 | 错误做法
|
||||
|----------------------|------
|
||||
|内部地, ... | 在里面, ...
|
||||
|创建集群。 | 打开新的集群。
|
||||
|首先, ... | 开头, ...
|
||||
|内部地，... | 在里面，...
|
||||
|创建集群。 | 打开新的集群。
|
||||
|首先，... | 开头，...
|
||||
|
||||
## 避免陈述未来{#avoid-statements-about-the-future}
|
||||
## 避免陈述未来 {#avoid-statements-about-the-future}
|
||||
|
||||
避免暗示或承诺未来。如果您需要讨论开发中的功能，请在标题下方添加一个样板，以便标识相应地信息。
|
||||
|
||||
### 避免过时的声明{#avoid-statements-that-will-soon-be-out-of-date}
|
||||
### 避免过时的声明 {#avoid-statements-that-will-soon-be-out-of-date}
|
||||
|
||||
避免使用“当前”和“新”之类的词。今天的新功能可能在几个月后就不会被视为新功能。
|
||||
|
||||
| 正确做法 | 错误做法
|
||||
|------------------------------------|------
|
||||
| 在版本 1.4 中 … | 在当前版本中 …
|
||||
| 联合身份验证功能提供 … | 新的联合身份验证功能提供了…
|
||||
| 在版本 1.4 中 ... | 在当前版本中 ...
|
||||
| 联合身份验证功能提供 ... | 新的联合身份验证功能提供了 ...
|
||||
|
|
|
|||
|
|
@ -12,46 +12,48 @@ keywords: [contribute, documentation, guide, code-block]
|
|||
|
||||
## Service {#service}
|
||||
|
||||
避免使用 **service** 这个说法。调查显示不同人对这个词的理解是不一样的。下面的表格展示了对读者更明确和清晰的说法：
|
||||
避免使用 **Service** 这个说法。调查显示不同人对这个词的理解是不一样的，
|
||||
下面的表格展示了对读者更明确和清晰的说法：
|
||||
|
||||
| 应该使用 | 不要使用
|
||||
|--------------------------------------------|-----------------------------------------
|
||||
| Workload A 发送一个请求到 Workload B. | Service A 发送一个请求到 Service B.
|
||||
| 当 。。。。。。的时候，新 workload 实例启动了 | 当 。。。。。。的时候，新 service 实例启动了
|
||||
| 这个应用程序包含 2 个 workload。 | 这个服务包含了 2 个 service。
|
||||
| 应该使用 | 不要使用
|
||||
|----------------------------------------------|-----------------------------------------
|
||||
| Workload A 发送一个请求到 Workload B。 | Service A 发送一个请求到 Service B。
|
||||
| 当 ... 的时候，新 Workload 实例启动了。 | 当 ... 的时候，新 Service 实例启动了。
|
||||
| 这个应用程序包含 2 个 Workload。 | 这个服务包含了 2 个 Service。
|
||||
|
||||
我们的术语表建立了商定的术语，并给出了避免混淆的定义。
|
||||
|
||||
## Envoy {#envoy}
|
||||
|
||||
相比 “proxy” 我们更喜欢使用 “Envoy” 这个词，因为它更具体，并且如果在整个文档中都使用一致的术语，更容易让大家理解。
|
||||
相比 "proxy" 我们更喜欢使用 "Envoy" 这个词，因为它更具体，并且如果在整个文档中都使用一致的术语，
|
||||
更容易让大家理解。
|
||||
|
||||
同义词：
|
||||
|
||||
- “Envoy sidecar” - 这样说没问题
|
||||
- “Envoy proxy” - 这样说没问题
|
||||
- “The Istio proxy” -- 最好避免这样说，除非说的是另外一个可能使用其它代理的高级场景。
|
||||
- “Sidecar” -- 大多时候仅限于概念文档中使用
|
||||
- “Proxy” -- 只有在上下文非常容易理解的时候
|
||||
- "Envoy sidecar" - 这样说没问题
|
||||
- "Envoy proxy" - 这样说没问题
|
||||
- "The Istio proxy" -- 最好避免这样说，除非说的是另外一个可能使用其它代理的高级场景。
|
||||
- "Sidecar" -- 大多时候仅限于概念文档中使用
|
||||
- "Proxy" -- 只有在上下文非常容易理解的时候
|
||||
|
||||
相关术语：
|
||||
|
||||
- Proxy agent - 这是一个较小的基础设施组件，应该只出现在低层的详细文档中。它不是专有名词。
|
||||
- Proxy agent - 这是一个较小的基础设施组件，应该只出现在底层的详细文档中。它不是专有名词。
|
||||
|
||||
## 其它 {#miscellaneous}
|
||||
|
||||
|应该使用 | 不要使用
|
||||
|----------------|------
|
||||
| addon | `add-on`
|
||||
| Bookinfo | `BookInfo`, `bookinfo`
|
||||
| Bookinfo | `BookInfo`、`bookinfo`
|
||||
| certificate | `cert`
|
||||
| colocate | `co-locate`
|
||||
| configuration | `config`
|
||||
| delete | `kill`
|
||||
| Kubernetes | `kubernetes`, `k8s`
|
||||
| Kubernetes | `kubernetes`、`k8s`
|
||||
| load balancing | `load-balancing`
|
||||
| Mixer | `mixer`
|
||||
| multicluster | `multi-cluster`
|
||||
| mutual TLS | `mtls`
|
||||
| service mesh | `Service Mesh`
|
||||
| sidecar | `side-car`, `Sidecar`
|
||||
| sidecar | `side-car`、`Sidecar`
|
||||
|
|
|
|||
Loading…
Reference in New Issue