风格指南

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: 字段的文本必须使用首字母大小写。即:除连词和介词外,将每个单词的首字母大写。

使用现在时

正确做法错误做法
命令启动代理服务器。命令将启动代理服务器。

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

使用主动句式

正确做法错误做法
您可以使用浏览器查询API。API可以使用浏览器被查询。
YAML 指定了副本数量。副本数量已被 YAML 指定。

使用简单直接的语言

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

正确做法错误做法
创建 ReplicaSet, …为了要创建 ReplicaSet, …
参见配置文件。请参见配置文件。
查看 Pods。通过下一个命令,可查看 Pods。

使用“您”称呼读者

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

创建语义清晰的链接

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

避免使用“我们”

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

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

避免俚语和方言

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

正确做法错误做法
内部地, …在里面, …
创建集群。打开新的集群。
首先, …开头, …

避免陈述未来

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

避免过时的声明

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

正确做法错误做法
在版本 1.4 中 …在当前版本中 …
联合身份验证功能提供 …新的联合身份验证功能提供了…