本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。
專案摘要
- 開放原始碼組織：
- moja 全域
- 技術撰稿人：
- Tlazypanda
- 專案名稱：
- FLINT 技術新手上路指南說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
FLINT 技術新手上路指南的說明文件，用於引導新貢獻者透過技術新手上路，讓新貢獻者輕鬆獲得維護人員提供的最低支援，輕鬆踏出第一步。
專案問題
以下列出與現行文件相關的最重大問題： - 整段當地設定指南的操作說明，導致新貢獻者難以開始使用。 - 多個 FLINT 存放區缺乏用途的說明文件，且沒有互相關聯，導致新手難以找出要安裝的存放區。 - Windows 安裝作業詳盡記錄，但以 Linux 為基礎的安裝說明文件仍有進步空間。- Git 工作流程目前不屬於說明文件的一部分
建議採行的做法
本提案介紹一項解決方案，引導新貢獻者透過技術新手上路課程，輕鬆向維護人員提供基本支援，輕鬆踏出第一步。方法是重構目前的說明文件，讓這項工具更適合初學者，同時維護一個獨立存放區，存放所有可用說明文件。這個專案分為三個階段： - 查看現有說明文件並進行重構：這個階段的目標是查看目前的指南並進行重構，確保新加入的貢獻者能簡明易懂。為了讓新手可以輕鬆使用說明文件，您也必須修改說明文件，加入徽章、表情符號，以及標示為僅限首次使用或第一個問題標記的問題標記。- 建立中央獨立文件存放區：這個階段的目標是將獨立存放區中，按邏輯順序提供的所有說明文件連結。包括訂購捐款規範、專案設定操作說明和逐步指南。 - 為新開發人員加入開發人員工作流程和社群網站：這個階段的目標是加入開發人員工作流程，內含專案的 Git 貢獻指南、專案的技術架構，以及測試和品質確保指南。建議社群網站將採用單一頁面應用程式，顯示工作流程、新貢獻者可領取的問題以及所有貢獻者名單。 第 1 階段：複習現有說明文件和重構：
修改下列存放區的現行說明文件： - FLINT：目前的說明文件內容不夠詳盡，且並未按照順序提供所需必要程式庫的順序。逐步教學指南分成不同的 PDF 檔案，但可透過更簡潔的方式集中彙整在同一處。此外，您也可以參考 Windows 安裝指南，但如果 Linux 安裝作業重新導向至 FLINT.docker 存放區，或許會有幫助。- FLINT.docker：目前的說明文件並未提供設定這個存放區的目的，就是透過 Docker 讓 Linux 安裝 FLINT。透過 Docker 的支援範圍僅限於 Ubuntu 18.04 (Bionic Beaver)，但可以延伸至其他以 Linux 為基礎的發行版本。目前的說明文件還需著重說明設定 dockerfile 的先後方式，並且要提供如何從 makefile 建構的足夠資訊。 - FLINT.example：目前的說明文件並未提供設定這個存放區的目的，其中使用 FLINT 的使用範例。您可以根據特定的執行指示，更妥善地區分不同的樣本執行作業。我們也需要將這個存放區連結到主要的 FLINT 存放區，讓使用者能夠瀏覽這裡，以便實際查看範例。
您必須在目前的說明文件中加入下列資訊： - 使用 Git 和 GitHub：我們會提供逐步操作說明，說明如何建立存放區、複製，以及設定存放區的遠端上游。同時也會說明如何依據最新主要執行個體重新建構及處理合併衝突。 - 徽章和表情符號：現行說明文件缺少徽章和表情符號，讓新加入的貢獻者感到賓至如歸，也更容易找出問題所在。 - 「初次使用/新手友善」問題的相關資訊：這會協助引導新貢獻者找到適合初學者的問題和社群網站。 - 有關 Import-me 存放區的資訊：Import-me 存放庫是快速啟動任何 Moja Global 儲存庫的基準範本。目前的說明文件並未提及相同的重要性。您必須更新資料庫，提及 Import-me 存放區，並按步驟選擇以此做為建立新存放區的範本。還有一個既定程序，可讓程式設計人員向匯入-me 存放區建議其他功能。
第 2 階段：建立獨立的集中式說明文件存放區：
用於託管平台的工具：
考慮使用這個代管平台工具時，建議採用「閱讀文件」，原因如下：- - 在不同代管平台間取得高度排名。 - 推送修訂版本時自動更新 - 由於龐大的社群使用這項服務，因此易於設定及疑難排解支援 - 文件採用 reStructuredText 格式，輸出內容是由 Sphinx 編譯。
依照邏輯順序將所有內容分門別類：
建議的內容順序如下：- - 開發人員說明文件簡介：本節將介紹 Moja Global 和 FLINT 簡介。 - 貢獻：本節包含「貢獻方式」(程式碼/回報錯誤/翻譯/說明文件/組織事件等) 和「行為守則」等子章節。 - 開發設定：本節包含「Git 與 GitHub 工作流程」、「Windows 安裝」和「Linux 安裝」等子章節。 - 開發人員工作流程：- 加入我們：這個部分會提供各種社交論壇，例如 Slack 頻道，以便與 Moja Global 保持聯繫並攜手合作。
第 3 階段：新增開發人員工作流程和社群網站，供新貢獻者參考：
開發人員工作流程說明文件：
開發人員工作流程說明文件包含下列子部分：
- 使用的技術堆疊/架構以及程式碼中各種模組：這份說明文件可協助您熟悉已實作的技術堆疊、程式碼集的各種程式庫和模組，進而熟悉新貢獻者。
- 整合式測試和涵蓋率工具：隆重介紹新貢獻者：CI/CD 管道工具用於測試、涵蓋率機器人和自動品質檢查。以及測試失敗時應負責的人員。
- 您也可以使用機器人來簡化工作流程，例如 Zulipbot：設計要顯示的內容範本及提供說明文件，讓使用者瞭解機器人，甚至藉由貢獻內容來改進機器人設定。
- 手動測試及提交提取要求：說明文件說明如何手動根據特定標準測試提取要求，以及在提交提取要求時上傳螢幕截圖/GIF 結果。
- 提取要求審查規範會依貢獻者制定：將特定團隊標記為待審查，以及在提取要求中加入「需要審查」等標籤，讓維護人員能夠回覆。
社群網站：
社群網站的功能如下：
- 工作流程相關資訊：工作流程包含新貢獻者的一系列操作，例如：提出第一個計時器問題，然後為其他人建立第一個計時器問題，並提供意見回饋及審查提取要求以協助他人。
- 僅限首次計時器問題清單：專為首次使用或新增貢獻者的問題列出。
- 過時問題清單：列出長時間沒有處理的問題清單，因此可供貢獻者選擇。
- 貢獻者清單：曾對 Moja 全球存放區貢獻心力的貢獻者名單。
- 近期貢獻者：最近為 Moja 全球存放區貢獻者名單。
- 加入即時通訊論壇的連結：加入 Slack 社群，協助解決查詢並進一步討論專案的資訊和連結。