Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- GenPipes
- Escritor técnico:
- shaloo
- Nombre del proyecto:
- Configurar 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 usuario / investigador nuevo
- Identificar información faltante, imprecisiones
- Sugerir nuevos temas de documentos (si es necesario)
- Crea un borrador de la arquitectura de la información para dirigirte al público objetivo, con énfasis en los usuarios nuevos.
(Nota: Durante este paso, es posible que también necesitemos la opinión de los mentores de GenPipes en relación con 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 las fuentes de documentos si es necesario seguir alguna. De lo contrario, se pueden usar los estándares, afaik. Además, en el caso de PoC, puedo hacer una demostración de la configuración de un 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 básico de estructura / índice propuesto para la Documentación de GenPipes y colócalo en el sitio de RTD
- Esto implica la creación del repositorio de GitHub (con las herramientas de Sphinx, por ejemplo) y los archivos de documentación básica.
- Esto también implica la creación de una nueva TOC que tenga en cuenta tanto a los usuarios nuevos como a los usos experimentados de las distintas secciones o flujos de información.
Revisar o obtener aprobación sobre el TOC del esqueleto desnudo
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 y aún no aparece públicamente en RTD. Independientemente de que aparezca como preseleccionado, esta demostración se puede usar para impulsar el esfuerzo de GenPipes RTD. Ya revisé las fuentes en el repositorio de GitHub de c3g/GenPipes. A los mentores, Rola y Héctor, les gustó el debate de "pantalla compartida" de Skype, por lo que pensé que los dioses de GSoD también podrían querer verlo. Por ahora es muy sencillo, pero pienso actualizarla cuando el tiempo lo permita hasta el 30 de julio.
https://genpipes.readthedocs.io/en/latest/
Paso 2: Creación del documento GenPipes v0.9
Identifica qué documentos de GenPipes actuales o existentes se pueden importar, vincular o convertir a documentación basada en Sphinx o en primer lugar para alojar en RTD. Ten en cuenta los cronogramas de GSoD.
Si es necesario, convierte los documentos identificados al primer formato, crea documentos nuevos cuando corresponda y reutiliza todo 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. Coloca una nota por adelantado que sugiera que los usuarios nuevos vayan a la documentación original de GenPipes hasta que se apruebe el cambio formal o la revisión.
Revisión/Corrección del curso/Actualización
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 TOC de GenPipes: agrega documentos adicionales además de los primeros (léeme de GenPipes), conceptos, instructivos, etcétera.
Agrega una demarcación clara en TOC para dirigirte a usuarios nuevos, usuarios experimentados de GenPipes, desarrolladores de GenPipes, etcétera.
Sugiere y analiza 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 documento GenPipes, y si C3G permitirá eso para los colaboradores de documentos externos. Es posible que esto requiera la creación de algunos lineamientos para 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 documentos de GenPipes.
Informe
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 GenPipes a largo plazo. O bien, si es necesario, capacita a otros para hacerlo. Podemos basarnos en el resultado de esos primeros 3 meses.
Además, sugeriría una idea adicional para la propuesta de proyecto: la creación de un resumen de páginas de GenPipes 3 que ayude a una incorporación fácil. Hoy en día, un usuario nuevo tiene que saltar mucho antes de comenzar a usar GenPipes, ya que la documentación es buena, pero dispersa y no propicia para los usuarios nuevos. No estoy seguro de si esto se podrá hacer en un plazo de 3 meses, pero me gustaría intentarlo.
Esta misma propuesta y cómo se originó (historial) también se puede ver en https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing