风格指南

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

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

标题句首字母大写

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

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

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

使用现在时

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

使用主动句式

使用简单直接的语言

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

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

创建语义清晰的链接

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

避免使用“我们”

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

避免俚语和方言

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

避免陈述未来

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

避免过时的声明

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