istio.io/content/zh/docs/releases/contribute/style-guide/index.md

title	description	weight	aliases	keywords
风格指南	介绍 Istio 文档所使用的风格规则。	11	/zh/docs/welcome/contribute/style-guide.html /zh/docs/reference/contribute/style-guide.html	contribute

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

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

标题句首字母大写

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

正确做法	错误做法
Configuring rate limits	Configuring Rate Limits
Using Envoy for ingress	Using envoy for ingress
Using HTTPS	Using https

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

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

使用现在时

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

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

使用主动句式

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

使用简单直接的语言

使用简单直接的语言。避免使用不必要的短语，例如："please"。

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

使用"您"称呼读者

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

创建语义清晰的链接

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

避免使用"我们"

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

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

避免俚语和方言

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

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

避免陈述未来

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

避免过时的声明

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

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