本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- gRPC-Gateway
- 技術撰稿人：
- iamrajiv
- 專案名稱：
- 重構 gRPC-Gateway 現有的說明文件網站
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要：
使用者文件網站旨在協助使用者使用產品或服務。良好的使用者說明網站非常重要，因為它能讓使用者瞭解如何使用軟體、軟體功能、訣竅和技巧，並解決使用軟體時遇到的常見問題。這麼做也可以降低支援成本，並成為產品的企業識別。良好的使用者文件網站是產品和開發人員團隊健康的象徵。如果沒有良好的使用者文件網站，使用者可能就無法有效且有效率地執行上述操作。使用者文件網站對於確保產品成功至關重要，因為良好的溝通是任何業務或產品的核心，而優質的文件就是將這項溝通內容放入可管理的架構中，讓每個人都能取得並成功使用。
在撰寫本文時，gRPC-Gateway 存放區已分支約 1, 200 次，且有 184 位使用者對這個存放區做出貢獻，這表示全球有許多人使用 gRPC-Gateway，並可能想閱讀相關使用者說明文件，瞭解如何使用 gRPC-Gateway。不過，gRPC-Gateway 使用者說明文件和說明文件網站目前已過時且不完整，而 gRPC-Gateway 社群希望透過這個專案重構現有的說明文件網站，改善說明文件網站，讓使用者在使用 gRPC-Gateway 時享有無縫體驗。
目前狀態：
目前，gRPC-Gateway 說明文件網站有兩個主要問題：
• 第一個問題是文件網站，因為網站及主題所用的樣式和結構已過時、不完整、難以瀏覽或尋找資訊，卻沒有涵蓋優質文件網站的許多功能。重構 gRPC-Gateway 現有的文件網站，將包括網站樣式、新增文件搜尋等功能、改善網站 UI、在適當的側欄中整理教學課程和範例，以及透過設計新版圖表和圖片來更新現有的圖表和圖片等。這將是我的首要目標，我的工作將著重於現有文件網站的樣式和重構。
• 第二個問題，需要重構 gRPC-Gateway 的現有文件、教學課程和範例等，方法是移除檔案中的排版和文法錯誤，讓 Go 程式碼片段保持正確對齊，並根據 Gofmt 格式重構 Go 程式碼片段。如有需要，我們也能視情況新增更多說明文件、教學課程和範例，也可以在重構後重複使用現有的檔案。這是我的次要目標，會在我完成主要目標 (即現有「Google 文件」網站的樣式和重組) 之後，再進行這些步驟。
我提議的文件網站對目前做法的效用為何？
建議的使用者文件網站經過架構設計，以提高效率、一致性和對使用者的安心。這麼做可提供更優質的介面和使用者介面，並以精心設計的版面和功能提供書面指南，以及相關的流程圖和圖片。
gRPC-Gateway 說明文件清楚說明瞭方法和範例。但它仍然使用舊的 Jekyll 主題，而現今的 SSG (靜態網站產生器) Jekyll 主題也較為完善。此外，您還必須重新調整頁面結構，加入新的示例和教學課程，並更新及重寫先前的內容，讓使用者享有更實用的體驗。
提案和構想的架構和藍圖：
這項專案的主要目標：-
您可以透過以下方式實作上述目標和想法：
改變目前的 Jekyll 主題，讓主題更臻完善、更強大。我們再次使用 Jekyll 主題的原因是，維護者已熟悉現有的 Jekyll 架構和主題，而這兩者與新的 Jekyll 主題相似，因此維護者可以輕鬆貢獻內容，並瞭解專案的工作流程。
在瀏覽過各種 Jekyll 主題後，我發現這個 https://idratherbewrite.com/documentation-theme-jekyll/ 主題套件最適合 gRPC-Gateway 文件網站，因為具有下列功能：
• Markdown：- 這樣技術作家就不必擔心安裝問題。他們可以直接在 .md 檔案中編寫內容。所有人都能點選網站上顯示的「編輯」按鈕 (新功能) 並提出 (編輯/建議 GitHub 中的頁面變更) 來提升內容品質。這有助於使用者新增新內容或修改內容，藉此提升網站品質。
• 文件搜尋：使用者應有搜尋框，方便快速輕鬆找到相關內容。
• 留言區：使用者可以選擇留言，並分享對貼文和教學課程的看法。他們可以閱讀其他人對專案說明文件的意見。
• 新版本資訊和網誌：- 網站應更新新的網誌文章，以及有關目前開發作業和路線圖的新聞。因此，到達網頁上應顯示這類的部落格文章。
• 快速開發：大多數的 SSG (靜態網站產生器) 架構會在伺服器中執行，檔案中的變更會立即反映在 UI 中。此外，部署和建構程序也應簡單易行。日後如要變更架構，我們會使用 然後可以輕鬆簡單。大多數的架構都支援 Markdown 寫作，因此只要移動 .md 檔案並進行少許變更，應該就足以完成轉換。
我要將現有的網站頁面分割成新的網站專區和頁面：
• 到達網頁：-
到達網頁應指出 gRPC-Gateway 的主要功能。
- 開始使用 gRPC-Gateway (重新導向至使用者指南)
- 簡單的安裝操作說明 (簡短指令)
- 使用 gRPC-Gateway 的好處
- 使用 gRPC-Gateway 的專案
因此，基本概念是不要寫長篇說明，而是在到達網頁中顯示主要重點，並提供連結，讓使用者前往查看詳細資料。
• gRPC-Gateway 使用者指南頁面：-
- 安裝指南。
- 快速開始使用 gRPC-Gateway。
• gRPC-Gateway 開發人員指南頁面：-
開發指南、貢獻指南、Git 設定、行為準則、文件設定、開發工作流程等，都會導向類似的頁面。因此，您需要重構並重新排列所有檔案。主要開發頁面應包含所有這些頁面，並在每個步驟中建立超連結。
• 關於 gRPC-Gateway 頁面：-
團隊專區應列出所有貢獻者的名單、快速連結和發布說明，並新增最新的部落格文章，吸引使用者閱讀目前的 gRPC-Gateway 新聞。
• 網誌、版本資訊和教學課程頁面：-
我認為網站應提供網誌選項。這樣一來，我們就能輕鬆傳達新聞和發布內容。教學課程頁面會提供一些熱門演講和文章，說明 gRPC-Gateway API 和相關概念。貢獻者可以在教學課程頁面中加入教學課程連結。
完成上述工作後，請在 v2 分支中更新相同的變更，並與 gRPC-Gateway 的主分支保持一致。
這項專案的次要目標：-
您還需要進行其他變更，讓 gRPC-Gateway 說明文件更穩健且易於閱讀：
• 修正 gRPC-Gateway 現有檔案中的文法和錯別錯誤，並整理及統整網站上的連結和文章。
• 視需要在 gRPC-Gateway 中新增更多說明文件和內容，因為大多數功能的說明文件都很短，例如 AWS 網站的「說明文件」部分、背景和用法等。
• 根據 Gofmt 格式重構 Go 程式碼片段 gRPC-Gateway
完成上述工作後，請在 v2 分支中更新相同的變更，並與 gRPC-Gateway 的主分支保持一致。
為何我適合參與這項專案：
我認為自己適合這個專案，因為：-
• 我曾協助改善機構組織的說明文件，也能使用任何版本管控系統，因此在 GitHub 上執行指令不會有任何問題。 • 此外，我很樂意參與能為使用者創造價值的專案。我認為，如果想讓某人以最有效率的方式做事，可以留下記錄。記錄程序可確保效率、一致性，並讓所有相關人員安心。• 我熟悉 gRPC-Gateway 的工作流程和程式碼庫，因為我過去兩個月一直在為 gRPC-Gateway 做出貢獻，並已合併 11 個 PR。