本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- GenPipes
- 技術文件撰寫者：
- shaloo
- 專案名稱：
- 在「閱讀說明文件」中設定 GenPipes 文件
- 專案長度：
- 標準長度 (3 個月)
Project description
我提議採用 3 個步驟的計畫，協助建立 GenPipes 說明文件中的「閱讀文件」。
步驟 1：聯絡窗口
以新使用者 / 研究人員的身分查看 GenPipes 現有的說明文件
- 找出遺漏的資訊、不正確的資訊
- 建議新的文件主題 (如有需要)
- 草稿資訊架構可用來對應目標對象，並著重於新使用者。
(注意：在這個步驟中，我們可能也會需要 GenPipes 導生針對新的 GitHub 存放區設定 (可代管 RTD 的基因段文件) 的輸入內容。這個 GitHub 存放區可用來匯入 RTD 建構管道中的所有文件。您可能需要針對 GenPipes 存放區規則和文件原始碼管理指南取得深入分析 (如有必要)。否則，也可以使用標準字型。另外，針對 PoC，我可以使用我的 GitHub 帳戶來示範 RTD 存放區設定範例，例如：https://gpdocs.readthedocs.io/en/latest/。這是我為這個提案建立的取樣器)。
根據上一個步驟的審查與分析，建立草擬的 GenPipes 說明文件結構 / 索引架構，並放到 RTD 網站上
- 這包括建立 GitHub 存放區 (例如透過 Sphinx 工具) 建立，以及基本的說明文件檔案
- 這也包含全新的新手上路技術中心，藉此在內容的各個部分 / 資訊流中牢記新使用者和資深使用需求。
查看 / 獲得裸機骨架《TOC》
在 GenPipes GSoD 評估階段，我嘗試透過由 RTD 代管的範例範例，為 GenPipes 創造價值。請注意，這項資訊僅供示範，僅供參考，尚未在 RTD 上公開列出。不論影片是否已列入候選名單，示範影片都能用來快速展開 GenPipes RTD。我已在 c3g/GenPipes GitHub 存放區中的來源檢查，在這之前，導師、Rola 和 Hector 對 Skype 的「分享螢幕」討論時很喜歡，所以我認為 GSoD Gods 或許也值得參考。這目前是 Barebone 骨架，但我計劃在時間允許前更新到 7 月 30 日。
https://genpipes.readthedocs.io/en/latest/
步驟 2：GenPipes 文件 v0.9 建立文件集
找出可匯入、連結或轉換為 Sphinx/rst 的現有或現有 GenPip 文件，以在代管 RTD 時考量 GSoD 時間表
視需要將指定文件轉換為 rst 格式，並視情況建立新文件，並視情況重複使用。
- 將這份初始文件匯入 ReadTheDocs 做為 Concept Proof 的概念，將文件託管為受保護的存放區。預先提醒新使用者，建議新使用者查看 GenPipes 原始說明文件，直到完成審查/正式轉換為止。
檢查/課程修正/最新消息
步驟 3：修正、檢查及發布 RTD 內容的第一份草稿
在 GenPipes TOC 中填入建議的 GenPipes 新文件結構 – 除了前幾份文件 (GenPipes Readme)、概念與教學課程等內容。
在 TOC 中加入明確的定義，以因應新使用者、經驗豐富的 GenPipes 使用者、GenPipes 開發人員等。
建議透過 RTD (sphinx 版本) 進行部分自動化作業，討論使用者如何維護、編輯 GenPipes 文件，以及 C3G 是否允許外部文件協作者進行這項作業。這可能需要建立一些文件更新規範，類似於程式設計指南。可能需要更多子步驟。例如，在 GenPipes 文件中自動檢查 PR 核准前的拼字檢查。
報表
最後，您可以根據自身經驗、記錄和導師意見回饋，製作 GSoD 報告。
其他想法
日後 (即 3 個月以後)，如果情況允許，我可以進一步協助 GenPipes 長期適用的使用這項功能。也可以視需要訓練其他地區使用者。我們可以根據這 3 個月的結果來確定。
此外，建議您提出其他專案提案，也就是建立 GenPipes 3 頁簡介，以便輕鬆上手。現在，新使用者必須先跳過很多人，才能開始使用 GenPipes，因為文件內容雖然好看，但又不容易閱讀給新使用者。不確定是否能在 3 個月內完成這項作業，但我想嘗試這次機會。
你也可以前往 https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing 查看這項提案及其相關流程 (歷史記錄)