GenPipes 專案
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- GenPipes
- 技術撰稿人：
- shaloo
- 專案名稱：
- 在「Read The Docs」中設定 GenPipes 說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
我建議採用 3 步驟計畫，以便在「Read The Docs」上設定 GenPipes 說明文件。
步驟 1：概念驗證
成為新使用者 / 研究者，查看現有的 GenPipes 文件
- 找出缺漏或不正確的資訊
- 建議新的文件主題 (如有需要)
- 草擬資訊架構地圖，以便針對目標對象 (特別是新使用者) 進行宣傳。
(注意：在這個步驟中，我們也可能需要 GenPipes 導師輸入有關新 GitHub 存放區設定的輸入內容，以便託管 RTD 的 RTD 文件。這個 GitHub 存放區可用於匯入 RTD 建構管道中的所有文件。您可能需要瞭解 GenPipes 存放區規則和文件來源管理指南 (如有)，才能遵循這些規定。否則，可以使用標準的。另外，為了證明概念可行，我可以使用自己的 GitHub 帳戶示範 RTD 存放區範例設定，例如 https://gpdocs.readthedocs.io/en/latest/ - 這是我為這項提案建立的範例)
根據前一個步驟的審查與分析，將建議的 GenPipes 文件結構 / 索引建立還沒有骨架，並放到 RTD 網站上
- 這涉及建立 GitHub 存放區 (例如使用 Sphinx 工具) 和基本文件檔案
- 此外，這也包括建立新的 TOC 結構，讓新使用者和經驗老到，能在不同部分 / 資訊流中靈活運用。
檢閱 / 取得裸機骨架 TOC 的核准
在 GenPipes GSoD 評估階段，我嘗試透過託管於 RTD 的這個範例，為 GenPipes 創造價值。請注意，這只是為了示範，因此是保護的連結，尚未在 RTD 上公開。無論我是否入圍決選，這項示範資源都能用於 GenPipes RTD 的起步工作。我已在 c3g/GenPipes GitHub 存放區的原始碼中檢查過。導師、Rola 和 Hector 先前在 Skype「分享螢幕」討論期間很喜歡這個項目，所以我覺得 GSoD 神奇也想看看。目前只是簡單的架構，但我預計在 7 月 30 日前，只要時間允許就會更新。
https://genpipes.readthedocs.io/en/latest/
步驟 2：GenPipes Doc v0.9 的文件集建立
步驟 3：在 RTD 中修訂、查看及發布第一份草稿
將 GenPipes 新文件結構的建議內容填入 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 查看這份提案和相關歷史記錄。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-07-25 (世界標準時間)。
[null,null,["上次更新時間：2025-07-25 (世界標準時間)。"],[[["\u003cp\u003eThis project aims to migrate and restructure GenPipes documentation to 'Read the Docs' for improved accessibility and user experience.\u003c/p\u003e\n"],["\u003cp\u003eThe project will involve a 3-step process: creating a proof-of-concept, building an initial documentation set, and refining/publishing the documentation.\u003c/p\u003e\n"],["\u003cp\u003eThe documentation will be tailored to different user groups including new users, seasoned users, and developers.\u003c/p\u003e\n"],["\u003cp\u003eThe project proposes establishing a workflow for ongoing maintenance and updates to the documentation, potentially involving automation and community contributions.\u003c/p\u003e\n"],["\u003cp\u003eAn additional goal is to create a concise onboarding guide for new GenPipes users to facilitate easier adoption.\u003c/p\u003e\n"]]],["The project aims to migrate GenPipes documentation to 'Read The Docs' (RTD). The plan involves three steps: 1) creating a proof of concept (PoC) by reviewing existing documentation, proposing a new structure, and setting up a basic RTD site; 2) creating a GenPipes v0.9 documentation set by converting, linking, or creating content, then hosting a protected version on RTD; 3) refining the documentation, including adding content, defining user sections, and establishing a maintenance process. A final report will summarize the work, and future maintenance is possible.\n"],null,["# GenPipes project\n\nThis page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\nProject summary\n---------------\n\nOpen source organization:\n: GenPipes\n\nTechnical writer:\n: shaloo\n\nProject name:\n: Set up GenPipes docs at 'Read The Docs'\n\nProject length:\n: Standard length (3 months)\n\nProject description\n-------------------\n\nI'm proposing a 3-step plan to achieve the objective of setting up GenPipes documentation on 'Read The Docs'.\n\n### Step 1: PoC\n\n- Review existing documentation of GenPipes as a new user / researcher\n\n - Identify missing information, inaccuracies\n - Suggest new doc topics (if required)\n - Draft information architecture map to address target audience, with a focus on new users.\n\n (Note: During this step, we may also need inputs from GenPipes mentors regarding a new GitHub repository setup where genpipes docs for RTD can be hosted. This GitHub repo can be used to import all docs in RTD build pipelines. This might require insights on GenPipes repo rules and doc source management guidelines if any need to be adhered to. Otherwise standard ones can be used, afaik. Also for PoC, I can demo a sample RTD repo setup using my GitHub account - for e.g., \u003chttps://gpdocs.readthedocs.io/en/latest/\u003e - this is a sampler that I created for this proposal)\n- Based on review and analysis in previous step, create a barebones skeleton of proposed GenPipes Documentation structure / index and put it up on RTD site\n\n - This involves GitHub repo creation (with Sphinx tooling for example) and basic documentation files\n - This also involves a new TOC creation that keeps both new users and seasoned uses in mind for various sections / flows of information.\n- Review / get approval on barebones skeleton TOC\n\n During GenPipes GSoD evaluation phase, I tried to create value for GenPipes through this sample hosted at RTD. Please note, this is for demo purposes only, protected link, not listed publicly on RTD yet. Irrespective of whether I get shortlisted, this demo can be used to jumpstart GenPipes RTD effort. I have already checked in the sources in c3g/GenPipes GitHub repo. The mentors, Rola and Hector liked it during Skype 'share screen' discussion earlier and so I thought GSoD Gods may want to see it too. Its barebones skeleton for now but I plan to update it when time permits until July 30.\n\n\u003chttps://genpipes.readthedocs.io/en/latest/\u003e\n\n### Step 2: GenPipes Doc v0.9 docset creation\n\n- Identify which current or existing GenPipes documents can be imported, linked or converted to Sphinx/rst based documentation for hosting on RTD keeping GSoD timelines in mind\n\n- Convert identified docs to rst format, if needed, create new ones where applicable, reuse whatever possible / relevant.\n\n - Import this initial doc set into ReadTheDocs as Proof of Concept -- host it there as a protected repo. Put a note upfront suggesting new users go to GenPipes original documentation until review/formal switch is given a go ahead.\n- Review/course-correct/update\n\n### Step 3: Refine, Review and Publish first draft at RTD\n\n- Fill in details of proposed GenPipes new doc structure into the GenPipes TOC -- Add additional docs besides the first few ones (GenPipes Readme), Concepts, Tutorials etc.\n\n- Add clear demarcation in TOC to address new users, seasoned GenPipes users, GenPipes developers, etc.\n\n- Suggest, discuss a working process with part automation via RTD (sphinx builds) on how GenPipes docset can be maintained, edited by users and if C3G will allow that for external doc contributors. This may require some guidelines creation for doc updates similar to coding guidelines. May require more sub-steps. For e.g., automate spell check before PR approval in GenPipes docs.\n\n### Report\n\nFinally, Create a report for GSoD based on experiences, logs, feedback from mentors.\n\n### Other thoughts\n\nIn future (beyond 3 months), if applicable, I can help maintain this for GenPipes on a longer term. Or train others, if required, for the same. We can figure this out based on the outcome of this first 3 months.\n\nAlso, I'd suggest additional project proposal idea - creation of a GenPipes 3 page brief that helps in easy on-boarding. Today, a new user has to jump many hoops before they can get started with GenPipes as the documentation is good but scattered and not conducive to new users. Not sure if this can be done within 3 months, but I'd like to try and give it a shot.\n\nThis same proposal and how it came about (history) can be also viewed at \u003chttps://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing\u003e"]]
