样式指南

本文为 Istio 文档提供内容指南。这是建议，不是规范，所以作者应自行做出最佳判断，也可以随时对本文以 PR 的形式提出变更建议。

格式标准

一致的大写方式

不建议使用大写的方式来表达强调。

在引用代码或配置文件中的名称的时候，应该以 `` 包围，不应该拆分为单词，并且要遵循原文的大小写方式，例如 IstioRoleBinding，不要改写为 Istio Role Binding 或者 istio role binding。

如果不是直接引用代码或配置内容，应该使用正常的大写方式，例如 “The Istio role binding configuration takes place in a YAML file.”

用尖括号标识占位符

使用下面的尖括号形式，告知读者占位符中想要表达的内容

1. 显示 Pod 的信息：

   $ kubectl describe pod <pod-name>
   

   这里的 <pod-name> 就是 Pod 的名称。

使用 **加粗显示** 表达用户界面元素

使用 **加粗显示** 定义或引入新词汇

使用 `code` 样式来表达文件名、目录名以及路径

使用 `code` 表达行内代码和命令

使用 `code` 表示对象的字段名称

Front-matter 中的 title 字段应该使用标题方式的大写

Front matter 中的 title: 应该使用标题格式：除了连词和介词之外，每个单词的首字母都大写。

这一点和将要提到的文章内的多级标题是不一样的。

各级标题中只对头一个单词进行首字母大写

任何级别的标题，只对第一个字母进行首字母大写，除非涉及到缩写和专有名词。

术语标准

为清晰起见，我们希望在文档中始终如一地使用一些标准术语。

Envoy

推荐使用 “Envoy”，这一称呼相对于 “proxy” 来说更加具体，在文档中更加容易呼应。

同义词：

• “Envoy sidecar” – 可以。
• “Envoy proxy” – 可以。
• “Istio proxy” – 最好避免，除非要谈论的是使用其他代理的高级场景。
• “Sidecar” – 绝大多数时间只会在概念性文档中使用。
• “Proxy” – 只在上下文非常清晰的时候使用。

相关词汇：

• Proxy agent：这是一个重要的基础设施组件，只会出现在底层细节的文档之中。这一称呼并非专有名词。

杂项

最佳实践

使用现在时

例外：在必要的时候还是要使用将来时或过去时的。

使用主动语态

例外: 在主动语态可能引起误会时，还是应该使用被动语态。

简单直接的表达方式

简单直接的陈述，避免使用不必要的文字，例如“请”。

称读者为“你”

使用有用的链接

链接有好坏。这里或者点击这里都是坏链接的例子。建议阅读下面链接中的文章，其中讲述了如何更好的使用超链接的问题，在创建或审核内容时，尝试遵循其中的建议。

Why “click here” is a terrible link, and what to write instead.

避免使用“我们”

在句子中使用“我们”会让人迷惑，读者不易分辨自己是否“我们”之中的一员。

避免使用行话和习语

英文是部分读者的第二语言，为了让更多读者更方便的理解内容，应避免使用行话和习语

避免预言

避免预言或承诺未来。如果需要进行关于 Alpha 特性的讨论，请在标题下方用文字清晰的声明 Alpha 的相关信息。

避免使用快速过时的描述

避免“当前”或者“新的”这样的用词。今天的新功能可能几个月后就不新了。