风格指南

Istio 文档所有的内容都必须 清晰明了易于理解。我们根据 Google 开发者风格指南中的重点通则定义了标准。关于您贡献的内容是如何被审核、接受的,请参见审核页面获取详情。

您可以在此通过 Istio 特有的示例,找到 Istio 遵循的基本风格与实践指南的所有场景。

标题句首字母大写

在您的文档中,为标题使用句首字母大写。即:仅将标题中第一个单词的首字母大写,专有名词或缩写除外。

正确做法错误做法
Configuring rate limitsConfiguring Rate Limits
Using Envoy for ingressUsing envoy for ingress
Using HTTPSUsing https

为 front-matter 中 title: 字段的值使用首字母大写

front-matter 中 title: 字段的文本必须使用首字母大小写。即:除连词和介词外,将每个单词的首字母大写。

使用现在时

正确做法错误做法
This command starts a proxy.This command will start a proxy.

例外:确实需要通过使用将来时或过去时才能表达正确的含义时。这种例外极为罕见,应尽可能的避免。

使用主动句式

正确做法错误做法
You can explore the API using a browser.The API can be explored using a browser.
The YAML file specifies the replica count.The replica count is specified in the YAML file.

使用简单直接的语言

使用简单直接的语言。避免使用不必要的短语,例如:“please”。

正确做法错误做法
To create a ReplicaSet, …In order to create a ReplicaSet, …
See the configuration file.Please see the configuration file.
View the Pods.With this next command, we’ll view the Pods.

使用“您”称呼读者{address-the-reader-as-you}

正确做法错误做法
您可以通过 …… 创建 Deployment我们将通过 …… 创建 Deployment
在前面的输出中,您可以看到……在前面的输出中,我们可以看到……

链接有语义清晰也有不是最佳做法的。如:在 此处单击此处 打开链接的常见做法就是不好的链接示例。 请查看这篇出色的文章, 其中解释了什么是好的超链接,并在创建或查看网站内容时牢记这些准则。

避免使用“我们”

在句子中使用“我们”可能会造成混淆,因为读者可能不知道他们是否属于您所描述的“我们”。

正确做法错误做法
1.4 版本中包括…在 1.4 版本中,我们添加了…
Istio 为 … 提供了一项新功能。我们提供了一个新功能……
该页面教您如何使用 Pod。在此页面中,我们将学习 Pod。

避免俚语和方言

一些读者的母语不是英语,避免使用术语和习惯用语,可用以帮助他们更轻松的理解。

正确做法错误做法
Internally, …Under the hood, …
Create a new cluster.Turn up a new cluster.
Initially, …Out of the box, …

避免陈述未来

避免暗示或承诺未来。如果您需要讨论开发中的功能,请在标题下方添加一个样板,以便标识相应地信息。

避免过时的声明

避免使用“当前”和“新”之类的词。今天的新功能可能在几个月后就不会被视为新功能。

正确做法错误做法
在版本 1.4 中 …在当前版本中 …
联合身份验证功能提供 …新的联合身份验证功能提供了…
这些信息有用吗?
Do you have any suggestions for improvement?

Thanks for your feedback!