本頁將詳細說明 Google Season of Docs 接受的技術文件寫作專案。
專案摘要
- 開放原始碼組織：
- 雲端原生運算基金會 (CNCF)
- 技術文件撰稿者：
- Shriti
- 專案名稱：
- 改善 SMI 和相關服務網格的說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
服務網格技術的目標在於處理所有安全性、管理和監控需求，為日益增加的服務提供價值。服務網格介面 (SMI) 定義了一組 API，用於最常見的服務網格用途 (流量政策、遙測和轉換)，並讓服務網格之間相容。服務網格是專用基礎架構層，可在微服務環境中處理服務與服務間的通訊。這些介面的標準化可提供更優質的使用者體驗，因此是 SMI 和相關服務網格的未來目標。
目前狀態：
使用者指南： SMI 是相對較新的沙箱專案，於 2020 年 4 月捐贈給 CNCF。因此，這個專案缺乏使用者說明文件。Meshery 是一個服務管理層，可為各種服務提供效能基準化服務，方便您採用、設定、操作及管理不同服務網格的效能，也針對在任何服務網格上執行的應用程式，收集與顯示其指標資料。因此，我會先提供 Meshery 指南，讓整個 SMI 使用者社群都能從中獲得啟發。
使用者教學課程： 在現有的 SMI 平台中： Learn Layer5 範例應用程式目前是 SMI 的學習裝置，也是用於驗證 SMI 規範的範例應用程式。但除此之外，SMI 專案完全沒有提供終端使用者教學課程，這對專案的技術性質而言是嚴重阻礙。Meshery 是展示 SMI 和相關服務網格優點和用途的絕佳應用程式，因此我會使用它做為展示 SMI 功能的基本工具。
API 說明文件：目前不存在。SMI 和各種相關專案的 API 端點在平台上都有定義。例如， Meshery 在 server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) 上定義了端點，但這些端點在外部並未廣為加註或記錄。 只要提供有意義的 API 說明文件，就能解決這個問題，而且只要新增讓使用者測試端點及預覽功能的方式，就能進一步改善。
數據分析：
建立使用者教學課程，可讓使用者參與並測試軟體。廣告必須具有互動性和美感，才能吸引使用者的注意，最重要的是易於使用。
不過，如果要撰寫或代管使用者手冊，建議採用較成熟的格式，因為使用者手冊通常是用於參考或快速解決問題。這類頁面不應具備互動性，而是應以條理分明的結構為重點，並著重於改善資訊清楚度、一致性和良好的使用者流程。
其中一種可行的解決方案是，透過 Google 程式碼研究室建立獨立的使用者教學課程，由 Jekyll 協助建立獨立的使用手冊，最後與 API 說明文件整合，為使用者和未來的協作者提供完善的使用體驗。
目標對象：SMI 專案為旗下所有專案提供部署和營運做法、學習環境和效能基準。這項服務適用於個人和機構。
使用者手冊：我會鎖定初學者，不假設使用者端具備既有 IT 知識。目標：初學者 原因：主要用於做為廣泛的參考指南，需要隨著時間更新。這份文件將提供詳細說明和實用提示，確保使用者能取得所有必要資訊，以便設定及使用服務中介網。視需要加入影片、相片、螢幕截圖和 GIF 檔案，讓指南更具吸引力且更符合使用者需求。
使用者教學課程： 目標：初學者 原因：重點是讓教學課程引人入勝且美觀，以吸引使用者注意，並讓他們順利測試軟體，進而更深入瞭解 Service Mesh 介面。
API 端點說明文件： 目標：進階使用者 原因：本節著重在使用更複雜的服務網格功能，這項功能更希望具備基本 IT 知識的進階使用者有興趣。 進階使用者會尋找簡明的教學課程，以便在需要時做為參考指南。端點說明文件應以這種方式撰寫，以便輕易更新，而不犧牲其準確性或一致性。這項程序最好是自動化程序。
資源： 使用者教學課程： Google 開發人員程式碼研究室 - 用於製作互動式且完整的使用者教學課程。 優點： - 可產生沙箱教學課程。 - 提供實作方法。- 使用 Google 文件撰寫，且支援 Markdown 文字。- 可使用 Google Analytics 進行監控 - 輕鬆觀察使用者流量。 - 易於使用。製作賞心悅目的教學課程，讓使用者直接操作軟體，完全不需直接投資。
您可以使用 CLaaT (Codelabs as a Thing) 專案強化 Google Codelab，並輕鬆部署。這個程式提供指令列工具，可用來將使用 Markdown 撰寫在 Google 文件中的教學課程，轉換為 Codelab (HTML) 格式。
使用者指南： Jekyll - 現有的 meshery.io 說明文件 (可在此處找到) 託管於 Jekyll，並使用 Docsy Jekyll 主題。它會使用 Markdown、liquid、HTML 和 CSS 產生可供代管的靜態網站，並在 Ruby 開發環境中執行。優點： - 可直接從 GitHub 存放區代管網站。- 這個專案擁有非常活躍的社群，因此支援完善的支援 - 只要將使用手冊和強化功能加入現有的 SMI 和 Meshery 說明文件，即可，不必煩惱遷移至其他平台。
API 說明文件：Swagger (或 Swaggo) 會用於為 SMI 和 Meshery 建立 API 說明文件。這是編寫 API 文件的簡便解決方案。優點： - 從 API 設計建立說明文件：確保說明文件隨 API 演進而保持最新狀態。- API 設計的說明文件：可透過 API 定義自動產生。- 維護多個說明文件版本 - 自訂 API 設計
專案目標： - 使用 Google Developer Codelabs 建立互動式使用者教學課程，針對 SMI 和相關服務網格使用 Meshery 做為工具。- 使用 Jekyll 為服務網格建立使用者指南。- 使用 Swagger 產生 SMI 的 API 端點說明文件。- 讓專案由社群驅動，讓未來和現有的使用者或開發人員在 SMI 社群的指導和審核下，輕鬆繼續擴充專案。
時間表： 建議的時間表請見這裡： https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
結構： 建議的使用者指南結構請見此處： https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
為何選擇這項專案？服務網格社群正以極快的速度擴張，這要歸功於最近將服務網格整合為 CNCF 沙箱專案。不過，這個專案的說明文件嚴重缺乏，不論是對使用者還是開發人員都一樣。我過去曾嘗試過各種服務網格，包括 linkerD 與 EmojiVoto 應用程式、Istio 與其 bookinfo 應用程式，以及 Hashicorp 的 Consul。我也嘗試過 SMI 流量拆分，並在服務網格設定中實作各種驗證規則。學習過程雖然有趣，但技術含量極高，因此可能會讓新使用者和開發人員卻步，不敢踏入服務網格社群，或不敢將服務網格用於個人或專業專案。我希望能彌補這項差距，但這需要提供有效且完善的說明文件和教學課程。