新增文件
若要為 Istio 貢獻新文件，請按照下列步驟操作
- 確定資訊的目標對象和預期用途。
- 選擇您要貢獻的內容類型。
- 選擇標題.
- 依照我們的文件貢獻指南撰寫您的貢獻。
- 將您的貢獻提交至我們的 GitHub 儲存庫。
- 遵循我們的審查流程，直到您的貢獻合併。
確定目標對象和預期用途
最好的文件從了解預期的讀者、他們的知識以及您希望他們如何使用資訊開始。否則，您無法判斷要提供的適當資訊範圍和深度、其理想結構或必要的支援資訊。以下範例展示了此原則的實際應用
讀者需要執行特定任務：告訴他們如何辨識何時需要該任務，並將該任務本身以編號步驟列表的形式提供，而不是僅以一般術語描述該任務。
讀者必須先理解概念才能執行任務：在說明任務之前，先告知他們必要的前提資訊，並提供相關連結。
讀者需要做決策：提供必要的概念資訊，以了解何時該做決策、可用的選項，以及何時該選擇哪個選項而不是另一個。
讀者是管理員但不是軟體工程師：提供腳本，而不是開發人員指南中程式碼範例的連結。
讀者需要擴展產品的功能：提供如何擴展功能的範例，並使用簡化的情境來說明。
讀者需要理解複雜的功能關係：提供顯示關係的圖表，而不是撰寫多頁冗長且難以閱讀和理解的內容。
最需要避免的常見錯誤是，因為不確定讀者需要哪些資訊，而只是簡單地將你擁有的所有資訊都提供給讀者。
如果您在確定內容的受眾方面需要協助，我們很樂意在文件工作組的雙週會議期間協助您並回答所有問題。
內容類型
當您了解受眾以及您提供資訊的預期用途時，您可以選擇最能滿足他們需求的內容類型。為了方便您選擇，下表顯示了支援的內容類型、它們的目標受眾以及每種類型力求實現的目標。
| 內容類型 | 目標 | 受眾 |
|---|---|---|
| 概念 | 說明 Istio 的一些重要面向。例如，概念頁面描述某個功能的配置模型並解釋其功能。概念頁面不包含步驟順序，而是提供相應任務的連結。 | 想要了解功能如何運作，且僅對專案有基本知識的讀者。 |
| 參考頁面 | 提供詳盡且詳細的技術資訊。常見範例包括 API 參數、命令列選項、配置設定和進階程序。參考內容是從 Istio 程式碼庫產生，並經過準確性測試。 | 對專案有進階且深入技術知識，需要特定資訊才能完成進階任務的讀者。 |
| 範例 | 描述一個運作中的獨立範例，其中重點介紹一組功能、Istio 與其他專案的整合，或是用例的端到端解決方案。範例必須使用現有的 Istio 設定作為起點。範例必須包含自動化測試，因為它們的技術準確性需要維護。 | 想要快速自行執行範例並進行實驗的讀者。理想情況下，讀者應該能夠輕鬆更改範例以產生自己的解決方案。 |
| 任務 | 顯示如何使用 Istio 功能達成單一目標。任務包含以步驟順序編寫的程序。任務對功能的解釋最少，但包含相關背景知識的概念連結。任務必須包含自動化測試，因為它們的技術準確性需要測試和維護。 | 想要使用 Istio 功能的讀者。 |
| 設定頁面 | 重點說明完成 Istio 部署所需的安裝步驟。設定頁面必須包含自動化測試，因為它們的技術準確性需要測試和維護。 | 想要完成部署的新用戶和現有 Istio 用戶。 |
| 部落格文章 | 重點關注 Istio 或與其相關的產品和技術。部落格文章分為以下三種類別
| 對專案有基本了解，想以軼事、經驗和更非正式的方式了解專案的讀者。 |
| 新聞項目 | 重點關注有關 Istio 和相關事件的及時資訊。新聞項目通常會發布新版本或即將舉行的活動。 | 想要快速了解 Istio 社群的新動態和事件的讀者。 |
| 常見問題解答項目 | 提供常見問題的快速解答。解答不介紹任何概念。相反，它們提供實用的建議或見解。解答必須連結到文件中的任務、概念或範例，以便讀者了解更多資訊。 | 有特定問題，正在尋找簡短解答和資源以了解更多資訊的讀者。 |
| 操作指南 | 重點說明實際解決方案，以解決在真實環境中運行 Istio 時遇到的特定問題。 | 想要修正問題或實作解決方案來運行 Istio 部署的服務網格操作人員。 |
選擇標題
為您的主題選擇一個標題，其中包含您希望搜尋引擎找到的關鍵字。Istio 中的所有內容檔案都命名為 index.md，但每個內容檔案都位於一個資料夾中，該資料夾使用主題標題中的關鍵字，以連字符分隔，全部小寫。盡可能縮短資料夾名稱，以使交叉引用更容易建立和維護。
將您的貢獻提交至 GitHub
如果您不熟悉 GitHub，請參閱我們的使用 GitHub 指南，以了解如何提交文件變更。
如果您想了解更多關於您的貢獻如何以及何時發佈的資訊，請參閱關於分支的章節，以了解我們如何使用分支和 cherry picking 來發佈我們的內容。