# 風格指南

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

以下的風格指南旨在幫助你了解雲端原生 Glossary 的定義結構，並在整個過程中保持一致的風格。

雲端原生詞彙遵循位於 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. 要簡明扼要

## 受眾

本 Glossary 是針對技術*和*非技術人員編寫的。
請使用簡單的術語來解釋定義並不要假定技術知識。有關定義的更多細節請參閱下面的[定義](#definition)部分。


## 最小可行定義

我們的目標是讓任何人都能夠輕鬆理解雲端原生術語。
因此，我們專注於簡潔明瞭。
請使用清晰簡單的語言，並提供任何使用技術的人都可以理解的示例，同時提供一個*最小可行定義*，至少從技術角度上來說。
我們不希望省略上下文和示例 — 畢竟，這些東西可以幫助讀者理解概念 — 但如果技術細節不需要理解它，我們就會跳過它。
目標不是讓事情變得過於複雜。一旦讀者了解了基本概念，其他資源將有助於他們進一步深入挖掘。
這部分超出了本 Glossary 的範圍。 

## 定義樣板

每個 Glossary 術語都存儲在一個 markdown 文件中，並遵循這個樣板：

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

## 是什麼

對該技術或概念的快速總結。

## 解決的問題

關於它所解決的問題的幾句話。

## 如何幫助我們

用幾句話說明這個東西是如何解決問題的。
```

### 標題

**title** label 將始終位於定義布局的頂部，其值應使用標題大小寫。

```md
---
title: 定義樣板
```

### 狀態

**status** label 將出現在 title label 之後。這個 label 代表著這個定義距離完成還有多遠。

有效值：

- Completed
- Feedback Appreciated
- Not Started

你可以隨時對一個已完成的定義提出議題。當一個定義處於變化中時，它的狀態將被改變為 *Feedback Appreciated*。

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

### Tags

**tag** label 跟隨著 status label。
為了讓 tag 有意義且對使用者有幫助，我們將嚴格使用它們。
應用太多的 tag 只會削弱其意義。
除了 `fundamental`，它僅表示需要理解其他雲端原生概念的術語；大多數術語可能只有一個 tag。

**注意**：請只在維護者批准的情況下引入新 tag。在為條目添加 tag 時，請確保它們的拼寫與下面列出的完全相同（單數，無錯字）。

目前的 tag 有：

- application
- architecture
- fundamental
- infrastructure
- methodology
- networking
- property
- security

```md
---
title: 定義樣板
status: Feedback Appreciated
tags: ["tag 1", "tag 2", ""]
---
```

### 定義

#### 三個小標題

**技術**和**概念**類別的定義包含三個小標題。

- **是什麼**：對我們正在談論的內容提供一個簡短而清晰的概述。
- **解決的問題**：關注問題，而不是解決方案（這在下一節會有）。避免提及所定義的術語。問題的重點是 *什麼* 導致我們需要那個東西。
- **如何幫助我們**：現在，回到這個術語上。它是如何解決上面描述的問題的？

注意，**屬性** 不需要單獨的章節。一個定義就足夠了。

為了便於審查，請使用**語義的換行符**（每行一句話）。

#### 品質至上

如果被合併，你的提交將成為該術語的 CNCF 官方定義（直到其他人改進它）。
創建一個符合 CNCF 高標準的術語不能操之過急，品質則需要時間和努力。

**做你的研究**：即使你確信你知道這個術語，也要驗證你是否得到了它。
我們經常在組織中以某種方式使用術語，但這可能並不反映全貌。
當你做研究時，特別是當你對這個術語不是 100% 熟悉時，要使用多種資源。
許多定義是片面的，尤其是由供應商提供的定義。Glossary 必須包含供應商中立的、全球公認的定義。

**不要盜竊**：同樣的規則適用於 Glossary 和任何其他嚴肅的出版物。
不要複製和粘貼其他人的作品，除非你是引用和貢獻給他們的。
如果你喜歡某個定義的某個部分，請用你自己的話來轉述它。

**參考權威資源**：在可能的情況下，連接到權威的資源，如專案文件。
注意，我們不能連接到供應商開發的內容。

#### 保持簡單

本 Glossary 旨在 **用簡單的文字解釋複雜的概念** --這是一項令人驚訝的艱巨任務，可能需要多次修訂。
在起草你的定義時，要始終牢記受眾。避免使用行業術語和流行語--你可能會發現自己又回到了這些術語和流行語，那時候你會需要訓練自己找找看其他的詞語。

在適當的時候，使用 **現實世界的例子**，幫助讀者（尤其是非技術性的）更好地理解你所解釋的概念在 *什麼時候* 和 *為什麼* 是相關的。

當在你的定義中使用時，一定要 **連接到現有的 Glossary 術語**（只有第一次提到的時候應該有超鏈接）。

**例子**：看看[服務網格](https://glossary.cncf.io/zh-tw/service-mesh/) 的"是什麼"部分。它鏈接到了微服務、服務、可靠性和可觀察性的定義。
此外，它還使用了一個真實的例子，將微服務環境中的網路挑戰（非技術人員無法理解的問題）與 wifi 問題（使用筆記型電腦的人都能理解的問題）進行比較。
在可能的情況下，嘗試建立這種聯繫。

#### 從 Google 或 Word 文件開始

我們建議從 Google 或 Word 文件開始，讓它靜置幾天，然後再重新審視。
這將使你能夠抓住那些可以用更直觀和更容易理解的方式來表達的短語或表達方式。
此外，確保在提交 PR 前進行拼寫檢查。

為了確保在工作期間沒有其他人提交 PR，請申請一個議題（或創建一個），並要求分配給你。更多資訊請參見[如何貢獻](https://glossary.cncf.io/zh-tw/contribute/) 文檔。

在開始之前，請閱讀一些已發表的 Glossary 術語，以了解其詳細程度和難度，以及何時舉例合適。

## 評審過程：期待什麼

請注意，我們目前只有兩個維護者在業餘時間做這個工作。
偶爾，我們會很快審查術語；在其他情況下，可能需要一些時間 — 我們感謝你的耐心。
如果你有任何問題，請在 #glossary-localization-traditional-chinese Slack 頻道與我們聯繫（關於在哪裡以及如何找到該頻道，請參考我們的[如何貢獻](https://glossary.cncf.io/zh-tw/contribute/) 文檔）。

我們的目標是讓雲端原生 Glossary 成為盡可能最好的資源。
一旦你提交了一個 PR，我們可能會要求進行一次或多次修改。
不要感到沮喪 — 許多 PR 都是這樣的情況。
這些來回的修改和我們的合作將確保你的貢獻成為一個有幫助的定義，被全球各地的讀者所閱讀和參考。

---

- Canonical URL: https://glossary.cncf.io/zh-tw/style-guide/
- Status: Completed
- 最後編輯 September 7, 2023: ` Update the style guide in Traditional Chinese (#2327) ` ([c39bfba](https://github.com/cncf/glossary/commit/c39bfba94a172511c8a0de273249f3f8a61ffde9))
- Source: https://github.com/cncf/glossary/blob/main/content/zh-tw/style-guide/_index.md
- License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)