文件風格指南

本頁面提供 Kubernetes 文件的寫作風格指南。這些是指導方針，而非規則。請運用您的最佳判斷，並隨時透過提取請求提議變更此文件。

如需建立 Kubernetes 文件新內容的更多資訊，請閱讀文件內容指南。

風格指南的變更由 SIG Docs 以群組形式進行。若要提議變更或新增內容，請將其新增至即將舉行的 SIG Docs 會議議程，並參加會議以參與討論。

語言

Kubernetes 文件已被翻譯成多種語言（請參閱 本地化 README）。

將文件本地化為不同語言的方式在本地化 Kubernetes 文件中進行了描述。

英文文件使用美式英語拼寫和語法。

文件格式標準

對於 API 物件使用 Upper Camel Case

當您特別指與 API 物件互動時，請使用 UpperCamelCase，也稱為 Pascal Case。您可能會在 API 參考中看到不同的首字母大寫，例如 "configMap"。在撰寫一般文件時，最好使用 Upper Camel Case，並稱之為 "ConfigMap"。

當您一般性地討論 API 物件時，請使用 句子式首字母大寫。

以下範例著重於首字母大寫。有關格式化 API 物件名稱的更多資訊，請查看關於程式碼風格的相關指南。

對於佔位符使用角括號

對於佔位符使用角括號。告訴讀者佔位符代表什麼，例如

顯示關於 Pod 的資訊

kubectl describe pod <pod-name> -n <namespace>

如果 Pod 的命名空間是 default，您可以省略 '-n' 參數。

對於使用者介面元素使用粗體

使用斜體來定義或介紹新術語

對於檔案名稱、目錄和路徑使用程式碼風格

對於引號內的標點符號使用國際標準

行內程式碼格式

對於行內程式碼、命令使用程式碼風格

對於 HTML 文件中的行內程式碼，使用 <code> 標籤。在 Markdown 文件中，使用反引號 (`)。然而，API 種類，例如 StatefulSet 或 ConfigMap，是逐字寫入的（沒有反引號）；這允許使用所有格撇號。

對物件欄位名稱和命名空間使用程式碼樣式

對 Kubernetes 命令工具和元件名稱使用程式碼樣式

以元件工具或元件名稱作為句子的開頭

使用一般描述詞而非元件名稱

對字串和整數欄位值使用一般樣式

對於字串或整數類型的欄位值，請使用不帶引號的一般樣式。

但是，如果讀者可能會將值與 API 種類混淆，請考慮使用引號。

參照 Kubernetes API 資源

本節討論我們如何在文件中參照 API 資源。

關於「資源」的澄清

Kubernetes 使用資源一詞來指稱 API 資源。例如，URL 路徑 /apis/apps/v1/namespaces/default/deployments/my-app 代表在「default」命名空間中名為 "my-app" 的 Deployment。在 HTTP 術語中，命名空間是一種資源 - 就像所有網頁 URL 都識別資源的方式一樣。

Kubernetes 文件也使用「資源」來談論 CPU 和記憶體請求與限制。通常最好將 API 資源稱為「API 資源」；這有助於避免與 CPU 和記憶體資源或其他種類的資源混淆。

如果您使用資源名稱的小寫複數形式，例如 deployments 或 configmaps，請提供額外的書面上下文，以幫助讀者理解您的意思。如果您在可以使用 UpperCamelCase 名稱的上下文中使用該術語，並且存在歧義的風險，請考慮使用 UpperCamelCase 中的 API 種類。

何時使用 Kubernetes API 術語

不同的 Kubernetes API 術語包括

• API 種類：API URL 中使用的名稱（例如 pods、namespaces）。API 種類有時也稱為資源類型。
• API 資源：API 種類的單一實例（例如 pod、secret）。
• 物件：作為「意圖記錄」的資源。物件是叢集特定部分的所需狀態，Kubernetes 控制平面嘗試維護該狀態。Kubernetes API 中的所有物件也是資源。

為了清楚起見，在 Kubernetes 文件中參照 API 資源時，您可以新增「資源」或「物件」。範例：寫「一個 Secret 物件」而不是「一個 Secret」。如果僅從大寫就清楚，則無需新增額外的詞彙。

當變更能幫助避免誤解時，請考慮改寫。常見的情況是當您想以 API 種類開頭一個句子時，例如「Secret」；因為英文和其他語言在句子開頭會大寫，讀者無法分辨您指的是 API 種類還是通用概念。改寫可以有所幫助。

API 資源名稱

始終使用 UpperCamelCase（也稱為 PascalCase）格式化 API 資源名稱。請勿使用程式碼格式設定 API 種類。

不要將 API 物件名稱拆分為單獨的單字。例如，使用 PodTemplateList，而不是 Pod Template List。

有關 PascalCase 和程式碼格式設定的更多資訊，請查看有關對 API 物件使用 UpperCamelCase和對行內程式碼、命令和 API 物件使用程式碼樣式的相關指南。

有關 Kubernetes API 術語的更多資訊，請查看有關Kubernetes API 術語的相關指南。

程式碼片段格式設定

不要包含命令提示字元

將命令與輸出分開

驗證 Pod 是否正在您選擇的節點上執行

kubectl get pods --output=wide

輸出類似於此

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Kubernetes 範例版本控制

包含版本資訊的程式碼範例和組態範例應與隨附的文字一致。

如果資訊是版本特定的，則需要在工作範本或教學課程範本的 prerequisites 區段中定義 Kubernetes 版本。儲存頁面後，prerequisites 區段會顯示為開始之前。

若要為工作或教學課程頁面指定 Kubernetes 版本，請在頁面的 front matter 中包含 min-kubernetes-server-version。

如果範例 YAML 位於獨立檔案中，請尋找並查看將其作為參考的主題。驗證任何使用獨立 YAML 的主題是否已定義適當的版本資訊。如果獨立 YAML 檔案未從任何主題中參照，請考慮刪除它而不是更新它。

例如，如果您正在撰寫與 Kubernetes 1.8 版相關的教學課程，則 markdown 檔案的 front-matter 應如下所示

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

在程式碼和組態範例中，請勿包含關於替代版本的註解。請注意不要在範例中包含不正確的陳述作為註解，例如

apiVersion: v1 # earlier versions use...
kind: Pod
...

Kubernetes.io 字詞表

在整個網站中一致使用的 Kubernetes 特定術語和單字列表。

短代碼 (Shortcodes)

Hugo 短代碼有助於建立不同的修辭訴求層級。我們的文件支援此類別中的三種不同短代碼：Note {{< note >}}、Caution {{< caution >}} 和 Warning {{< warning >}}。

1. 用開頭和結尾短代碼包圍文字。

2. 使用以下語法來套用樣式

   {{< note >}}
   No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
   {{< /note >}}
   

   輸出為

   注意

   您選擇的前綴與標籤的文字相同。

注意

使用 {{< note >}} 來突顯提示或可能有幫助的資訊。

例如

{{< note >}}
You can _still_ use Markdown inside these callouts.
{{< /note >}}

輸出為

您可以在清單中使用 {{< note >}}

1. Use the note shortcode in a list

1. A second item with an embedded note

   {{< note >}}
   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   {{< /note >}}

1. A third item in a list

1. A fourth item in a list

輸出為

1. 在清單中使用 note 短代碼

2. 包含嵌入式 note 的第二個項目

   注意

   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   

3. 清單中的第三個項目

4. 清單中的第四個項目

Caution

使用 {{< caution >}} 來提醒注意重要的資訊，以避免陷阱。

例如

{{< caution >}}
The callout style only applies to the line directly above the tag.
{{< /caution >}}

輸出為

Warning

使用 {{< warning >}} 來指示危險或必須遵循的重要資訊。

例如

{{< warning >}}
Beware.
{{< /warning >}}

輸出為

常見的短代碼問題

編號清單

除非您在通知和標籤之前縮排四個空格，否則短代碼會中斷編號清單。

例如

1. Preheat oven to 350˚F

1. Prepare the batter, and pour into springform pan.
   {{< note >}}Grease the pan for best results.{{< /note >}}

1. Bake for 20-25 minutes or until set.

輸出為

1. 將烤箱預熱至 350˚F

2. 準備麵糊，倒入彈簧扣模具。

   注意

   為了獲得最佳效果，請在烤盤上塗油。

3. 烘烤 20-25 分鐘或直到定型。

包含陳述式

包含陳述式內的短代碼會破壞建置。您必須將它們插入父文件中的 include 呼叫之前和之後。例如

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Markdown 元素

換行

使用單一換行符號來分隔區塊層級內容，例如標題、清單、圖片、程式碼區塊等。例外情況是二級標題，應為兩個換行符號。二級標題緊隨一級標題（或標題）之後，沒有任何先前的段落或文字。兩個換行符號的間距有助於在程式碼編輯器中更好地視覺化內容的整體結構。

在適當的情況下，在 Markdown 原始碼中手動換行段落。由於 git 工具和 GitHub 網站以逐行方式產生檔案差異，手動換行長行有助於審閱者輕鬆找出 PR 中所做的變更並提供回饋。它還有助於下游本地化團隊，人們可以在逐行基礎上追蹤上游變更。換行可以發生在句子結尾或標點符號處，例如。一個例外是 Markdown 連結或短代碼預期在單行中。

標題和標題

存取此文件的人員可能會使用螢幕閱讀器或其他輔助技術 (AT)。螢幕閱讀器是線性輸出裝置，它們一次輸出頁面上的項目。如果頁面上有大量內容，您可以使用標題為頁面提供內部結構。良好的頁面結構有助於所有讀者輕鬆瀏覽頁面或篩選感興趣的主題。

段落

連結

清單

將清單中彼此相關且需要以特定順序顯示或指示多個項目之間關聯性的項目分組。當螢幕閱讀器遇到清單（無論是有序清單還是無序清單）時，它會向使用者宣告有一組清單項目。然後，使用者可以使用箭頭鍵在清單中的各個項目之間上下移動。網站導覽連結也可以標記為清單項目；畢竟它們只是一組相關連結。

• 如果清單中的一個或多個項目是完整句子，請在清單中的每個項目末尾加上句點。為了保持一致性，通常應該全部項目或全部不應是完整句子。

  注意

  作為不完整介紹性句子一部分的有序清單可以使用小寫字母並加上標點符號，就好像每個項目都是介紹性句子的一部分一樣。

• 對於有序清單，請使用數字一 (1.)。

• 對於無序清單，請使用 (+)、(*) 或 (-)。

• 在每個清單後方留一個空白行。

• 使用四個空格 (例如，⋅⋅⋅⋅) 縮排巢狀清單。

• 清單項目可能包含多個段落。清單項目中的每個後續段落都必須縮排四個空格或一個 Tab 鍵。

表格

資料表的語意目的是呈現表格化的資料。視覺使用者可以快速掃描表格，但螢幕閱讀器會逐行瀏覽。表格標題用於為資料表建立描述性標題。輔助技術 (AT) 使用 HTML 表格標題元素來識別頁面結構中表格的內容，以提供給使用者。

• 使用 Hugo shortcodes 為表格新增表格標題。

內容最佳實務

本節包含針對清晰、簡潔且一致的內容所建議的最佳實務。

使用現在式

例外：如果需要傳達正確的含義，請使用未來式或過去式。

使用主動語態

例外：如果主動語態導致不自然的句子結構，請使用被動語態。

使用簡單且直接的語言

使用簡單且直接的語言。避免使用不必要的短語，例如說「請」。

以「您」稱呼讀者

避免使用拉丁文短語

相較於拉丁文縮寫，偏好使用英文術語。

例外：針對 et cetera，請使用「etc.」。

應避免的模式

避免使用「我們」

在句子中使用「我們」可能會造成混淆，因為讀者可能不知道他們是否是您描述的「我們」的一部分。

避免使用術語和慣用語

有些讀者以英文作為第二語言。避免使用術語和慣用語，以幫助他們更好地理解。

避免關於未來的陳述

避免做出承諾或給予關於未來的暗示。如果您需要談論 Alpha 功能，請將文字放在標題下，以識別其為 Alpha 資訊。

此規則的一個例外是關於已宣布棄用，目標是在未來版本中移除的文件。此類文件的其中一個範例是已棄用 API 移轉指南。

避免很快就會過時的陳述

避免使用諸如「目前」和「新的」等詞語。今天新的功能在幾個月後可能不被認為是新的。

避免使用假設特定理解程度的詞語

避免使用諸如「just」、「simply」、「easy」、「easily」或「simple」等詞語。這些詞語沒有增加價值。

EditorConfig 檔案

Kubernetes 專案維護一個 EditorConfig 檔案，該檔案設定文字編輯器 (例如 VS Code) 中的通用樣式偏好設定。如果您想確保您的貢獻與專案的其餘部分保持一致，可以使用此檔案。若要檢視該檔案，請參閱儲存庫根目錄中的 .editorconfig。

下一步

• 了解關於撰寫新主題。
• 了解關於使用頁面範本。
• 了解關於自訂 Hugo shortcodes。
• 了解關於建立提取請求。