Proyecto GenPipes

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.

Resumen del proyecto

Organización de código abierto:
GenPipes
Escritor técnico:
shaloo
Nombre del proyecto:
Configura los documentos de GenPipes en "Read The Docs".
Duración del proyecto:
Duración estándar (3 meses)

Project description

Propongo un plan de 3 pasos para lograr el objetivo de configurar la documentación de GenPipes en "Read The Docs".

Paso 1: PoC

  • Revisa la documentación existente de GenPipes como usuario / investigador nuevo

    • Identificar la información faltante y las imprecisiones
    • Sugerir temas nuevos para el documento (si es necesario)
    • Crea un borrador del mapa de arquitectura de la información para abordar al público objetivo, con un enfoque en los usuarios nuevos.

    Nota: Durante este paso, es posible que también necesitemos aportes de los mentores de GenPipes sobre la configuración de un nuevo repositorio de GitHub en el que se puedan alojar los documentos de GenPipes para RTD. Este repo de GitHub se puede usar para importar todos los documentos en canalizaciones de compilación de RTD. Esto puede requerir estadísticas sobre las reglas del repositorio de GenPipes y lineamientos para la administración de fuentes de documentos, si es necesario cumplirlos. De lo contrario, se pueden usar los estándares, según mi conocimiento. También para la PoC, puedo mostrar una configuración de muestra del repositorio de RTD con mi cuenta de GitHub (p. ej., https://gpdocs.readthedocs.io/en/latest/, que es un ejemplo que creé para esta propuesta).

  • Según la revisión y el análisis del paso anterior, crea un esqueleto básico de la estructura o el índice propuestos de la documentación de GenPipes y colócalos en el sitio de RTD.

    • Esto incluye la creación del repositorio de GitHub (con las herramientas Sphinx, por ejemplo) y los archivos de documentación básica
    • Esto también implica la creación de un nuevo glosario que tenga en cuenta a los usuarios nuevos y a los experimentados para varias secciones o flujos de información.

  • Revisar o obtener la aprobación del índice del esqueleto básico

    Durante la fase de evaluación de GSoD de GenPipes, intenté crear valor para GenPipes a través de esta muestra alojada en RTD. Ten en cuenta que esto es solo para fines de demostración, es un vínculo protegido y aún no se muestra públicamente en RTD. Independientemente de si me eligen, esta demostración se puede usar para iniciar el esfuerzo de I+D de GenPipes. Ya revisé las fuentes en el repositorio de GitHub de c3g/GenPipes. A los mentores, Rola y Héctor, les gustó durante la conversación anterior sobre la "compartir pantalla" de Skype, así que pensé que los dioses de GSoD también querrían verlo. Por ahora, es un esqueleto básico, pero planeo actualizarlo cuando el tiempo lo permita hasta el 30 de julio.

https://genpipes.readthedocs.io/en/latest/

Paso 2: Creación del conjunto de documentos de GenPipes Doc v0.9

  • Identifica qué documentos actuales o existentes de GenPipes se pueden importar, vincular o convertir a documentación basada en Sphinx/rst para alojarlos en RTD teniendo en cuenta los cronogramas de GSoD

  • Convierte los documentos identificados al formato rst, si es necesario, crea otros nuevos cuando corresponda y reutiliza lo que sea posible o relevante.

    • Importa este conjunto de documentos inicial a ReadTheDocs como prueba de concepto y alójalo allí como un repositorio protegido. Agrega una nota al principio en la que se sugiera a los usuarios nuevos que consulten la documentación original de GenPipes hasta que se apruebe la revisión o el cambio formal.

  • Review/course-correct/update

Paso 3: Define mejor, revisa y publica el primer borrador en RTD

  • Completa los detalles de la nueva estructura de documentos propuesta de GenPipes en el ÍNDICE de GenPipes. Agrega documentos adicionales además de los primeros (Leer GenPipes), conceptos, instructivos, etcétera.

  • Agrega una demarcación clara en el TOC para dirigirte a usuarios nuevos, usuarios experimentados de GenPipes, desarrolladores de GenPipes, etcétera.

  • Sugerir y analizar un proceso de trabajo con automatización de partes a través de RTD (compilaciones de Sphinx) sobre cómo los usuarios pueden mantener y editar el conjunto de documentos de GenPipes y si C3G lo permitirá para los colaboradores externos de documentos. Esto puede requerir la creación de algunos lineamientos para las actualizaciones de documentos similares a los lineamientos de codificación. Es posible que requiera más pasos secundarios. Por ejemplo, automatiza la revisión ortográfica antes de la aprobación de las PR en los documentos de GenPipes.

Denunciar

Por último, crea un informe para GSoD en función de las experiencias, los registros y los comentarios de los mentores.

Otras ideas

En el futuro (más de 3 meses), si corresponde, puedo ayudar a mantener esta información para GenPipes a largo plazo. O bien capacita a otras personas, si es necesario, para que hagan lo mismo. Podemos determinarlo en función del resultado de estos primeros 3 meses.

Además, te sugiero una idea adicional para la propuesta de proyecto: la creación de un resumen de la página de GenPipes 3 que ayude a una fácil integración. Hoy en día, un usuario nuevo tiene que hacer muchas jugadas antes de poder comenzar a usar GenPipes, ya que la documentación es buena, pero está dispersa y no es propicia para nuevos usuarios. No sé si esto se puede hacer en 3 meses, pero me gustaría intentarlo.

Esta misma propuesta y cómo surgió (historial) también se pueden ver en https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing