本頁將詳細說明 Google Season of Docs 接受的技術文件寫作專案。
專案摘要
- 開放原始碼組織：
- moja global
- 技術撰稿人：
- Tlazypanda
- 專案名稱：
- FLINT 技術新手上路指南說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
為 FLINT 編寫技術新手上路指南的文件，為新貢獻者提供技術新手上路指南，讓新手可以輕鬆上手，並減少維護者的支援需求。
專案問題
以下是目前說明文件中最重要的問題清單： - 本地設定指南的說明步驟不夠條理，因此新貢獻者難以開始使用。- FLINT 的多個存放區缺少其用途文件，且彼此未相互連結，導致新手難以找出要安裝的存放區。 - 說明 Windows 安裝程序的文件相當完善，但 Linux 安裝程序的說明文件仍有改進空間。- Git 工作流程目前不在說明文件的範圍內
建議採行的做法
本提案旨在引導新加入者完成技術新手上路程序，讓新貢獻者只需獲得維護人員的最少支援，就能輕鬆踏出第一步。您可以透過重構現有說明文件，讓說明文件更適合初學者，並維護中央獨立存放區，以便提供所有說明文件。這個專案分為三個階段：- - 檢查現有文件和重構：這個階段的目標是檢查目前的指南，並以簡潔易懂的方式重構，方便新貢獻者閱讀。您也需要修改說明文件，加入徽章、表情符號，以及標示為「僅限新手」或「適合新手」的議題資訊，讓說明文件更適合初學者。- 建立中央獨立說明文件存放區：這個階段的目標是在獨立存放區中，以邏輯順序連結所有可用的說明文件。包括排序貢獻指南、專案設定操作說明和逐步指南。- 為新開發人員新增開發人員工作流程和社群網站：這個階段的目標是新增開發人員工作流程，其中包含 Git 貢獻指南、專案的技術架構，以及測試和品質評估指南。建議的社群網站將是一個單頁應用程式，顯示工作流程、新貢獻者可聲明的初次問題，以及所有貢獻者的清單。階段 1：查看現有文件和重構：
修改下列存放區的現有說明文件： - FLINT：現有的說明文件不夠詳細，且未提供必要程式庫的順序。逐步操作說明指南分為多個 PDF 檔案，但可以以更簡潔的方式整合在單一位置。此外，安裝指南適用於 Windows，但如果是 Linux 安裝，將安裝作業重新導向至 FLINT.docker 存放區可能會更有幫助。- FLINT.docker：目前的說明文件未說明設定此存放區的目的，也就是透過 Docker 提供 FLINT 的 Linux 安裝程序。透過 Docker 提供的支援僅限於 Ubuntu 18.04 (Bionic Beaver)，但可擴充至其他 Linux 發行版本。目前的文件也需要強調 Dockerfile 的設定順序，並提供足夠的資訊，說明如何從 makefile 建構。- FLINT.example：目前的說明文件未說明設定此存放區的目的，也就是提供 FLINT 使用方式的範例。您可以按照特定指示，妥善分隔不同的樣本。我們也需要將這個存放區連結至主要的 FLINT 存放區，讓使用者能夠前往該處查看實際運作中的範例。
您需要將下列資訊新增至目前的文件： - Git 和 GitHub 用途：這會提供逐步操作說明，說明如何分支、複製，然後設定存放區的遠端上游。也會提供如何根據最新主版本重新設定基準，以及處理合併衝突的相關資訊。- 徽章和表情符號：目前的說明文件缺少徽章和表情符號，這會讓新貢獻者感到受歡迎，並讓他們在發現問題時不至於感到害怕。- 新手/初學者適用的問題資訊：這有助於將新貢獻者導向初學者適用的問題和社群網站。- Import-me 存放區相關資訊：Import-me 存放區是啟動任何 Moja Global 存放區的基準範本。目前的說明文件未提及這項重要資訊。這份文件需要更新，以便提及 Import-me 存放區，並新增建立新存放區時選擇此存放區做為範本的步驟。程式設計人員也應有固定程序，可針對 Import-me 存放區提出其他功能建議。
第 2 階段：建立中央的獨立說明文件存放區：
用於代管平台的工具：
建議為此代管平台採用的工具為《閱讀說明文件》，原因如下：- - 在不同的代管平台之間，排名很高。 - 在推送修訂版本時自動更新 - 易於設定及疑難排解支援，因為廣大社群需要這麼做 - 說明文件採用 reStructuredText 進行格式化，輸出結果則由 Sphinx 編譯。
以邏輯順序整理所有內容：
建議的內容順序如下：- - 開發人員文件簡介：本節將介紹 Moja Global 和 FLINT。 - 貢獻：這個部分將包含「貢獻方式」(程式碼/回報錯誤/翻譯/文件/安排活動等) 和「行為準則」兩個子部分。 - 開發設定：這個部分將包含「Git 和 GitHub 工作流程」、「Windows 安裝」和「Linux 安裝」三個子部分。 - 開發人員工作流程：這個部分將討論整合用於測試的工具，以及如何手動測試您的提取要求，以及更多在下一階段記錄的內容。 - 加入我們：這個部分會提供各種社群論壇 (例如 Slack 頻道)，讓您與 Moja Global 建立聯繫並合作。
階段 3：為新貢獻者新增開發人員工作流程和社群網站：
開發人員工作流程說明文件：
開發人員工作流程說明文件將包含下列子部分：
- 使用的技術堆疊/架構和程式碼中的各種模組：說明文件，讓新貢獻者熟悉已導入的技術堆疊、程式碼集的各種程式庫和模組。
- 整合測試和涵蓋率工具：為用於測試的 CI/CD 管道工具引入新貢獻者，並針對其程式碼執行涵蓋率機器人和自動化品質檢查。並提供指引，說明測試失敗時應聯絡誰。
- 用於簡化工作流程的機器人，例如 Zulipbot：設計機器人要顯示的內容範本，以及可供使用者瞭解機器人，甚至透過貢獻改善機器人設定的文檔。
- 手動測試及提交提取要求：提供說明文件，說明如何根據特定標準手動測試提取要求，以及在提交提取要求時，根據螢幕截圖/GIF 上傳結果。
- 提交者應遵循的提取要求審查規範：針對特定團隊加上標記以供審查，並在提取要求中加入「需要審查」等標籤，讓維護者回覆。
社群網站：
社群網站將提供下列功能：-
- 工作流程相關資訊：工作流程包含新貢獻者可進行的一系列操作，例如領取首次計時器問題，然後為他人建立第一個計時器問題，然後提供意見回饋及審查他們的提取要求。
- 僅限新手的議題清單：專為新手或新貢獻者提供的議題清單。
- 過時問題清單：列出長時間未解決的問題，可供貢獻者挑選。
- 貢獻者清單：目前為止，為 Moja Global 存放區貢獻內容的貢獻者清單。
- 最近的貢獻者：最近為 Moja Global 存放區貢獻內容的貢獻者清單。
- 加入即時通訊論壇的連結：提供加入 Slack 社群的資訊和連結，以便解決他們的問題，並進一步討論專案。