本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- gRPC-Gateway
- 技術文件撰寫者：
- iamrajiv
- 專案名稱：
- 重構 gRPC-Gateway 的現有文件網站
- 專案長度：
- 標準長度 (3 個月)
Project description
策略：
使用者文件網站旨在協助使用者使用產品或服務。完善的使用者文件網站至關重要，因為它能讓使用者瞭解軟體的使用方式、功能、提示、秘訣，以及使用軟體時的常見問題。而且能降低支援成本，而且屬於產品的公司身分。優質的使用者文件網站代表了產品 (開發團隊) 的健康。如果沒有完善的文件網站，使用者可能就無法有效率地執行上述作業。使用者文件網站是確保產品成效的關鍵要素，因為良好的溝通絕對是任何企業或產品的核心；完善說明文件只需提供可管理的資訊，並將其放入易於管理的架構，讓所有人都能存取所需資料。
撰寫本文時，已為 gRPC-Gateway 存放區建立大約 1200 次分支，而這個存放區有 184 位使用者參與了這個存放區。由此可見，全球有許多人都在使用 gRPC-Gateway，也想參閱 gRPC-Gateway 的使用說明文件，瞭解如何使用 gRPC-Gateway。不過，gRPC-Gateway 使用者說明文件和文件網站現已過時且不完整，gRPC-Gateway 社群則希望透過這項專案重構現有的文件網站，藉此改善現有文件網站的品質，讓使用者在使用 gRPC-Gateway 時享有流暢的使用體驗。
目前狀態：
目前 gRPC-Gateway 文件網站有以下兩個主要問題：-
• 第一個問題是不良，而且文件網站本身已經過時、不完整、難以瀏覽或尋找資訊，而且未涵蓋優質文件網站的許多功能。重構 gRPC-Gateway 的現有文件網站，包括設定網站的樣式、新增文件搜尋功能等功能、改善網站使用者介面、在適當的側欄中整理教學課程和範例，以及設計新流程圖和圖片來更新現有的流程圖和圖片。這將成為我的主要目標，我的工作將以現有的文件網站樣式和結構更相關。
• 第二項問題需要重構 gRPC-Gateway 現有的說明文件、教學課程和範例等等，方法是移除檔案之間的字體排版和文法錯誤，使 Go 程式碼片段正確對齊，並根據 Gofmt 格式重構 Go 程式碼片段。此外，我們可以視需要新增更多文件、教學課程和範例，或重構後重複使用現有的檔案。這是我的次要目標，我會在達成主要目標 (例如設定現有 Google 文件網站的樣式和架構) 後執行此動作。
我的提案網站為何比目前版本更完善？
建議的使用者文件網站架構經過精心設計，不但可提升效率，也能確保使用者體驗一致，讓使用者高枕無憂。如此一來，就能讓外觀和使用者介面擁有更美觀的專區和功能，並附上書面指南，以及相關的流程圖和圖片。
gRPC-Gateway 說明文件提供詳盡的方法和範例說明。但仍採用舊版的 Jekyll 主題，而現代的 SSG (靜態網站產生器) Jekyll 主題也更加完善。此外，您也必須新增範例和教學課程，並更新並改寫先前的內容，以期讓使用者覺得更實用的網頁架構。
規劃目標和構想的結構與輪廓：
這項專案的主要目標：-
上述目標和提案可以透過下列方式實踐：-
調整目前的 Jekyll 主題，讓主題更出色、更完善。再次使用 Jekyll 主題的原因是，維護人員已經知道現有的 Jekyll 架構和主題，而這和新的 Jekyll 主題很類似，因此能夠輕鬆地貢獻及瞭解專案的工作流程。
在網路上研究不同的 Jekyll 主題後，我認為這個 https://idratherbewriting.com/documentation-theme-jekyll/ 主題套件最適合 gRPC-Gateway 文件網站，因為具備以下功能：
• Markdown：- 技術撰寫者無須擔心安裝問題。只需在 .md 檔案中編寫即可。任何人都可以點選網站上顯示的編輯按鈕 (新功能)，並對 GitHub 中的網頁做出編輯/建議變更，協助改善服務品質。吸引使用者新增內容或編輯內容，進而提升內容成效。
• 說明文件搜尋：- 使用者應該要提供搜尋框，以便輕鬆快速地找到相關內容。
• 留言區：- 使用者可以選擇對貼文和教學課程留言及分享看法。能夠查看其他人對專案說明文件的檢視畫面。
• 新版本資訊和網誌：- 網站應更新，以便加入新的網誌文章，以及有關目前開發和藍圖的最新資訊。因此到達網頁應含有這類網誌。
• 快速開發：- 大部分的 SSG (靜態網站產生器) 架構正在伺服器中執行，檔案中的變更會立即反映在使用者介面中。此外，部署和建構程序也應易於處理。日後如果想變更架構，我們就會使用。然後應該要能輕鬆操作。大多數的架構都支援 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。