Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- GenPipes
- Redactor técnico:
- shaloo
- Nombre del proyecto:
- Configura los documentos de GenPipes en "Leer los documentos"
- 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 "Leer los documentos".
Paso 1: PoC
Revisar la documentación existente de GenPipes como nuevo usuario / investigador
- Identificar información faltante, imprecisiones
- Sugerir nuevos temas de documentos (si es necesario)
- Crea borradores de mapas de arquitectura de la información para dirigirse al público objetivo y centrarse en los usuarios nuevos.
(Nota: Durante este paso, es posible que también necesitemos comentarios de mentores de GenPipes sobre la configuración de un nuevo repositorio de GitHub donde se pueden alojar documentos de genpipes para RTD. Este repositorio 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 los lineamientos de administración de fuentes del documento si es necesario cumplir con alguna. De lo contrario, se pueden usar las estándar, afaik. Además, para la PoC, puedo hacer una demostración de una configuración de repositorio de RTD de muestra con mi cuenta de GitHub (p.ej., https://gpdocs.readthedocs.io/en/latest/; esta es una muestra que creé para esta propuesta)
Según la revisión y el análisis del paso anterior, crea un esqueleto simple de estructura / índice propuesto para la documentación de GenPipes y colócalo en el sitio de RTD
- Esto implica la creación de repositorios de GitHub (con las herramientas Sphinx, por ejemplo) y archivos de documentación básica.
- Esto también implica la creación de un nuevo TOC que tiene en cuenta tanto a los nuevos usuarios como a los usos experimentados para varias secciones / flujos de información.
Revisar y obtener aprobación sobre el TOC esqueleto básico
Durante la fase de evaluación de GenPipes GSoD, traté de 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, vínculo protegido, aún no aparece públicamente en RTD. Independientemente de que me incluya en la lista reducida, esta demostración se puede usar para impulsar el esfuerzo de RTD de GenPipes. Ya revisé las fuentes en el repositorio de GitHub de c3g/GenPipes. A los mentores, Rola y Héctor, les gustó durante el debate sobre la función de pantalla compartida de Skype, por lo que pensé que a los dioses de la GSoD también les gustaría verlo. Es muy sencillo por ahora, pero pienso actualizarla 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 de GenPipes actuales o existentes se pueden importar, vincular o convertir en documentación basada en Sphinx o la primera para alojarla en RTD teniendo en cuenta los cronogramas de GSoD.
Si es necesario, convierte los documentos identificados al primer formato, 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. Pon una nota por adelantado que sugiera que los usuarios nuevos consulten la documentación original de GenPipes hasta que se aprueben la revisión o el cambio formal.
Revisar/corregir/actualizar/actualizar
Paso 3: Define mejor, revisa y publica el primer borrador en RTD
Completa los detalles de la nueva estructura de documentos de GenPipes propuesta en el TOC de GenPipes: agrega documentos adicionales además de los primeros (lectura de GenPipes), conceptos, instructivos, etc.
Agregar una demarcación clara en el TOC para dirigirte a usuarios nuevos, usuarios experimentados de GenPipes, desarrolladores de GenPipes, etcétera.
Sugiere un proceso de trabajo con automatización de partes a través de RTD (compilaciones de esfinge) sobre cómo los usuarios pueden mantener y editar el archivo GenPipes, y si C3G permitirá eso para colaboradores de documentos externos. Es posible que esto requiera la creación de algunos lineamientos para las actualizaciones de documentos similares a los de programación. Es posible que se requieran más pasos secundarios. Por ejemplo, automatizar el corrector ortográfico antes de la aprobación de RR.PP. en los documentos de GenPipes.
Denuncia
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 esto para los GenPipes a largo plazo. También puedes capacitar a otras personas, si es necesario, para lo mismo. Podemos averiguarlo en función del resultado de los primeros 3 meses.
Además, sugeriría 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 divertirse mucho antes de comenzar a usar GenPipes, ya que la documentación es buena, pero dispersa y no propicia para los usuarios nuevos. No sé si se puede hacer en un plazo de 3 meses, pero me gustaría intentarlo.
Puedes ver esta misma propuesta y cómo surgió (historial) en https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing