GenPipes project

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