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:
- CERN‐HSF
- Redactor técnico:
- John
- Nombre del proyecto:
- CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials
- Duración del proyecto:
- Larga duración (5 meses)
Project description
CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials Mentor: Olivier Couet, Axel Naumann
Resumen: La documentación es esencial para que los usuarios adopten el software de manera exitosa y eficiente. La documentación del usuario clara, precisa y completa facilita la competencia de los usuarios con el software a medida que se esfuerzan por alcanzar sus objetivos. En ese sentido, los ejemplos y los instructivos explícitos sirven como herramientas poderosas con las que los usuarios pueden aprender rápidamente.
A medida que examinamos el uso de ROOT por parte de físicos, investigadores y desarrolladores dentro del espacio de análisis y visualización de datos para la física, se reconoce los beneficios de la documentación actualizada y fácil de usar. En particular, debido a la amplitud del código fuente y su crecimiento, el sistema de documentación se beneficia de la evolución en paralelo para otorgar a los usuarios la capacidad de maximizar todo lo que ROOT tiene para ofrecer.
Resumen y análisis de la documentación actual Actualmente, la documentación para el usuario ofrece una guía que permite a los físicos adoptar ROOT con mayor facilidad en relación con un público general. Además, en ciertos temas, como las vinculaciones dinámicas de Python, se podrían realizar mejoras para que la documentación sea más completa y clara. Del mismo modo, al nuevo formato de datos RNTuple le faltan las especificaciones detalladas necesarias. Por último, en la documentación actual faltan instructivos relacionados con ROOT 7.
Metodología: Después de consultar con Olivier, parece que, para abordar los problemas mencionados anteriormente, el enfoque principal debe incluir la identificación de brechas de conocimiento entre investigadores especializados y un público general, la creación de documentación para cerrar esa brecha, la redacción de una documentación más detallada de las vinculaciones dinámicas de Python, la implementación de “instructivos para el análisis moderno” para ROOT 7 y la creación de especificaciones técnicas detalladas para RNTuple. En ese sentido, durante este proceso, la documentación podría incorporar notebooks de Jupyter para que las herramientas de aprendizaje tangibles e interactivas puedan ayudar a los usuarios.
Cronograma: Se estima que las etapas del proyecto son las siguientes: Identificar las brechas de conocimiento entre los investigadores especializados y el público general (mientras se lee la documentación y el código fuente actuales) → 1 a 2 semanas Crear y refactorizar la documentación para cerrar esa brecha → 3 semanas Escribir una documentación más detallada de las vinculaciones dinámicas de Python → 3 semanas Implementar instructivos para las vinculaciones dinámicas de Python → 3 semanas Implementar instructivos para ROOT 7 → 4 semanas Crear especificaciones técnicas detalladas para RNTuple → 3 semanas Revisar si se completaron correctamente los objetivos del proyecto → 1 semana
Entregas y lineamientos para el éxito: Documentación del usuario unificada sin ninguna brecha Documentación del usuario completamente actualizada para reflejar las funciones más recientes, es decir, nuevas clases derivadas Instructivos a través de notebooks de Jupyter