GenPipes project
Stay organized with collections
Save and categorize content based on your preferences.
This page contains the details of a technical writing project accepted for
Google Season of Docs.
Project summary
- Open source organization:
- GenPipes
- Technical writer:
- shaloo
- Project name:
- Set up GenPipes docs at 'Read The Docs'
- Project length:
- Standard length (3 months)
Project description
I'm proposing a 3-step plan to achieve the objective of setting up GenPipes documentation on 'Read The Docs'.
Step 1: PoC
Review existing documentation of GenPipes as a new user / researcher
- Identify missing information, inaccuracies
- Suggest new doc topics (if required)
- Draft information architecture map to address target audience, with a focus on new users.
(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., https://gpdocs.readthedocs.io/en/latest/ - this is a sampler that I created for this proposal)
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
- This involves GitHub repo creation (with Sphinx tooling for example) and basic documentation files
- This also involves a new TOC creation that keeps both new users and seasoned uses in mind for various sections / flows of information.
Review / get approval on barebones skeleton TOC
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.
https://genpipes.readthedocs.io/en/latest/
Step 2: GenPipes Doc v0.9 docset creation
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
Convert identified docs to rst format, if needed, create new ones where applicable, reuse whatever possible / relevant.
- 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.
Review/course-correct/update
Step 3: Refine, Review and Publish first draft at RTD
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.
Add clear demarcation in TOC to address new users, seasoned GenPipes users, GenPipes developers, etc.
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.
Report
Finally, Create a report for GSoD based on experiences, logs, feedback from mentors.
Other thoughts
In 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.
Also, 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.
This same proposal and how it came about (history) can be also viewed at https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-11-08 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-08 UTC."],[[["\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"]]
