# 风格指南

> For AI agents: the complete glossary index is at [llms.txt](https://glossary.cncf.io/zh-cn/llms.txt).
> Markdown versions of every glossary page are available by appending `index.md` to the page URL.

以下的风格指南旨在帮助你了解云原生词汇表的定义结构，并在整个过程中保持一致的风格。

云原生词汇遵循位于CNCF资源库中的 [默认风格指南](https://github.com/cncf/foundation/blob/master/style-guide.md)。此外，它还遵循以下规则：

1. 使用简单、易懂的语言，避免技术术语和流行语
2. [避免使用俗语](https://en.wikipedia.org/wiki/Colloquialism)
3. [使用字面和具体的语言](https://guidetogrammar.org/grammar/composition/abstract.htm)
4. [省略缩略语](https://en.wikipedia.org/wiki/Contraction_(grammar))
5. [少用被动语态](https://www.ef.com/ca/english-resources/english-grammar/passive-voice/)
6. [力求以积极的形式表述](https://examples.yourdictionary.com/positive-sentence-examples.html)
7. [引号外不加感叹号](https://www.grammarly.com/blog/exclamation-mark/)
8. 不要夸大其词
9. 避免重复
10. 要简明扼要

## Definition Template

每个词汇表术语都存储在一个 markdown 文件中，并遵循这个模板：

```md
---
title: 
status: 
category: 
---

## 是什么

对该技术或概念的快速总结。

## 解决的问题

关于它所解决的问题的几句话。

## 如何帮助

用几句话说明这个东西是如何解决问题的。
```

### 标题

**title** 标签将始终位于定义布局的顶部，其值应使用标题大小写。

```md
---
title: 定义模板
```

### 状态

**status** 标签将出现在标题标签之后。状态标签表明定义是经过彻底审查还是未完成的。

有效值：

- Completed
- Feedback Appreciated
- Not Started

你可以随时对一个已完成的定义提出问题。当一个定义处于变化中时，它的状态将被改变为 *Feedback Appreciated*。

```md
---
title: 定义模版
status: Feedback Appreciated
```

### 类别

**category** 标签将出现在状态标签之后。它的值应该是以下值之一：

- 技术
- 属性
- 概念

```md
---
title: 定义模版
status: Feedback Appreciated
category: 概念
---
```

### 定义

该定义包含三个小标题，为读者提供背景："是什么"，"解决的问题"，以及 "如何帮助"。
对于技术和概念类的术语来说，这三个标题都是必须的，然而，属性类的定义则不需要这些标题。

#### 三个小标题

**技术** 和 **概念** 类别的定义包含三个小标题。

- **是什么**：对我们正在谈论的内容提供一个简短而清晰的概述。
- **解决的问题**：关注问题，而不是解决方案（这在下一节会有）。事实上，避免提及所定义的术语。问题的重点是 *什么* 导致我们需要那个东西。
- **如何帮助**：现在，回到这个术语上。它是如何解决上面描述的问题的？

注意，**属性** 不需要单独的章节。一个定义就足够了。

为了便于审查，请使用 **语义的换行符**（每行一句话）。

#### 质量是最重要的

如果被合并，你的提交将成为该术语的 CNCF 官方定义（直到其他人改进它）。创建一个符合CNCF高标准的术语不能操之过急，质量需要时间和努力。

**做你的研究**：即使你确信你知道这个术语，也要验证你是否得到了它。我们经常在组织中以某种方式使用术语，但这可能并不反映全貌。
当你做研究时，特别是当你对这个术语不是100%熟悉时，要使用多种资源。许多定义是片面的，尤其是由供应商提供的定义。词汇表必须包含供应商中立的、全球公认的定义。

**不要剽窃**：同样的规则适用于词汇表和任何其他严肃的出版物。不要复制和粘贴其他人的作品，除非你是引用和贡献给他们的。
如果你喜欢某个定义的某个部分，请用你自己的话来转述它。

**参考权威资源**：在可能的情况下，链接到权威的资源，如项目文件。注意，我们不能链接到供应商开发的内容。

#### 保持简单

本词汇表旨在 **用简单的文字解释复杂的概念** --这是一项令人惊讶的艰巨任务，可能需要多次修订。
在起草你的定义时，要始终牢记受众。避免使用行业术语和流行语--你可能会发现自己又回到了这些术语和流行语，而且可能需要自动更正。

在适当的时候，使用 **现实世界的例子**，帮助读者（尤其是非技术性的）更好地理解你所解释的概念在 *什么时候* 和 *为什么* 是相关的。

当在你的定义中使用时，一定要 **链接到现有的词汇表术语**（只有第一次提到的时候应该有超链接）。

**例子**：看看 [服务网格](https://glossary.cncf.io/zh-cn/service_mesh/)的 "是什么" 部分。它链接到了微服务、服务、可靠性和可观察性的定义。
此外，它还使用了一个真实的例子，将微服务环境中的网络挑战（非技术人员无法理解的问题）与 wifi 问题（使用笔记本电脑的人都能理解的问题）进行比较。在可能的情况下，尝试建立这种联系。

#### 从 Google 或 Word 文档开始

我们建议从 Google 或 Word 文档开始，让它静置几天，然后再重新审视。
这将使你能够抓住那些可以用更简单和更容易理解的方式来表达的短语或表达方式。
此外，确保在提交 PR 前进行拼写检查。

为了确保在工作期间没有其他人提交 PR，请确保申请一个问题（或创建一个），并将其分配给你。更多信息请参见 [如何贡献](https://glossary.cncf.io/zh-cn/contribute/) 文档。

在开始之前，请阅读一些已发表的词汇表术语，以了解其详细程度和难度，以及何时举例合适。

## 评审过程：期待什么

请注意，我们目前只有三个维护者在业余时间做这个工作。偶尔，我们会很快审查术语；在其他情况下，可能需要一些时间--我们感谢你的耐心。
如果你有任何问题，请在 #glossary Slack 频道与我们联系（关于在哪里以及如何找到该频道，请参考我们的 [如何贡献](https://glossary.cncf.io/zh-cn/contribute/) 文档）。

我们的目标是让云原生词汇表成为尽可能最好的资源。一旦你提交了一个 PR，我们可能会要求进行一次或多次修改。不要感到沮丧--许多 PR 都是这样的情况。
这些来回的修改和我们的合作将确保你的贡献成为一个真正有用的定义，被全球各地的读者所阅读和参考。

---

- Canonical URL: https://glossary.cncf.io/zh-cn/style-guide/
- Status: Completed
- 最后编辑 August 16, 2022: ` Some fixes (#1181) ` ([e8cb8ee](https://github.com/cncf/glossary/commit/e8cb8ee1937bab03c59d5cc4e83578f0dc784495))
- Source: https://github.com/cncf/glossary/blob/main/content/zh-cn/style-guide/_index.md
- License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)