本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- 雲端原生運算基金會 (CNCF)
- 技術文件撰寫者：
- Shriti
- 專案名稱：
- 改善 SMI 和相關服務網格的說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
服務網格技術主要用於處理所有安全性、管理和監控需求，讓更多服務發揮價值。 服務網格介面 (SMI) 會針對最常見的服務網格用途 (流量政策、遙測和轉移) 定義一組 API，並支援服務網格之間的相容性。服務網格是專門的基礎架構層，可用來處理微服務環境中的服務對服務通訊。將這些介面標準化，有助於改善使用者體驗，因此是 SMI 和相關服務網格的未來目標。
目前狀態：
使用手冊：SMI 是新的沙箱專案，2020 年 4 月捐款給 CNCF。因此，缺少使用者的說明文件。網格是一種服務管理層，能針對各種服務提供效能基準化服務，幫助他們採用、設定、操作和管理不同服務網格的效能。此外，網格還能針對在任何服務網格中運作的應用程式，收集與顯示指標資料。因此，我想先提供關於網蘭車的指南，做為整個 SMI 使用者社群的起點。
使用者教學課程： 在現有的 SMI 平台中： 範例應用程式 (Learn Layer5) 目前可做為 SMI 的學習裝置，以及用於執行 SMI 規格驗證的範例應用程式。然而，由於 SMI 專案缺乏使用者教學課程，這會是專案技術性高度不足的缺陷。要在展示 SMI 和相關服務網格的優點和應用方面，Landery 是最適合的應用程式，因此我會將其做為展示 SMI 功能的基礎工具。
API 說明文件：目前不存在。SMI 和各種相關專案在平台中已定義其 API 端點。舉例來說，Lryery 的端點是在 server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) 定義，但並未在外部註解或記錄。 您可以透過實用的 API 說明文件來解決這個問題，同時新增供使用者測試端點及預覽功能的方式，藉此強化這項功能。
數據分析：
建立使用者教學課程的目的，是讓使用者參與軟體測試，並為其執行測試。這類元素必須互動、設計美觀，才能維持使用者的注意力，最重要的是簡單易用。
不過，在撰寫或代管「使用者指南」時，建議您考慮採用較成熟的格式，因為使用者指南通常可做為參考指南，或專門用於快速修正問題的平台。這類模型的結構必須完善，並著重於提高明確性、一致性及良好使用者流程，而非互動式內容。
要解決這個問題，可行的方法是使用 Google 程式碼研究室和獨立的使用手冊，搭配 Jekyll 使用，最後再與 API 說明文件整合，藉此為使用者和日後的協作者提供全面性的使用體驗。
目標對象：SMI 專案可為其下的所有專案提供部署與營運做法、學習環境和效能基準。適合個人和機構使用。
使用手冊：我以初學者為目標對象，完全不會假設使用者既有的 IT 知識。 目標：初學者 原因：主要用於大量參考指南，因此需要時間更新。其中包含深入解說和實用提示，確保使用者擁有所有必要資訊，可以設定及使用服務網格。為了讓這份指南更引人入勝，也更容易理解，使用者可以視需要新增影片、圖片、螢幕截圖和 GIF。
使用者教學課程： 目標：新手 原因：課程重點是製作引人入勝且美觀的教學課程，使教學課程更能有效抓住使用者的注意力，並讓軟體能夠流暢地執行測試，進而更加瞭解服務網格介面。
API 端點說明文件： 目標：進階使用者 原因：本節著重介紹使用更複雜的服務網格功能，對具備基本 IT 知識的進階使用者更感興趣。進階使用者尋找的是簡單明瞭的教學課程，並視需要做為參考指南。端點說明文件應採用適當的撰寫方式，以便在降低準確率或一致性的情況下輕鬆進行更新。最好採用自動化程序。
資源： 使用者教學課程： Google Developers 程式碼研究室 - 製作互動式完善的使用者教學課程。 優點： - 可產生沙箱教學課程。 - 可以實際操作。 - 使用 Google 文件撰寫，並支援 Markdown 文字。 - 可使用 Google Analytics (分析) 進行監控，輕鬆觀察使用者流量。 - 易於使用。製作兼具美感的教學課程，讓使用者無須直接投資即可直接操作軟體。
您可以使用 CLaaT (程式碼研究室做為 Thing) 專案，強化並輕鬆部署 Google 程式碼研究室 - 這個程式提供指令列工具，可將使用 Markdown 編寫的教學課程轉換為程式碼研究室 (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 和相關服務網格的互動式使用者教學課程，並搭配使用 Rickery 做為工具。 - 使用適用於服務網格的 Jekyll 來建立使用手冊。- 使用 Swagger 產生 SMI 的 API 端點說明文件。 - 將專案社群做為主導方向，讓現有及現有的使用者或開發人員在 SMI 社群的指南與審核程序中輕鬆繼續添加內容。
時間軸： 如需預訂時程，請前往以下網址： https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#書籤=kix.j1b6m64eubsl
結構： 如需《使用手冊》的架構，請前往： https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
為什麼是這個專案？ 我們最近已將服務網格社群整合至 CNCF，因此服務網格社群的發展速度飛快無比。不過，對使用者和開發人員而言，這項專案都獲得了大量說明文件。我過去曾嘗試過各種服務網格，例如含有 EmojiVoto 應用程式的連接器、Istio 及其簿資訊應用程式，以及 Hashicorp’s Consul。我也試過 SMI 流量分配功能，並對我的服務網格設定實作各種驗證規則。學習過程很有趣，但技術高超，對於新使用者和開發人員而言，能在採用服務網格社群的第一步，或者將服務網格用於自己的個人或專業專案。我想彌補這方面的不足，只能透過有效率且記錄詳盡的指南和教學課程來完成。