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:
- CERN‐HSF
- Redactor técnico:
- Juan
- Nombre del proyecto:
- CERN-HSF: Documentación ROOT para la adopción del público general, instructivos y vinculaciones dinámicas de Python
- Duración del proyecto:
- Larga duración (5 meses)
Project description
CERN-HSF - Documentación ROOT para la adopción del público general, instructivos y vinculaciones dinámicas de Python Mentor: Olivier Couet, Axel Naumann
Abstracto: La documentación es esencial para una adopción exitosa y eficiente de software por parte de los usuarios. La documentación del usuario clara, completa y precisa facilita que los usuarios dominen el software a medida que se esfuerzan por alcanzar sus objetivos. En ese sentido, los instructivos y ejemplos explícitos sirven como herramientas potentes 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 de la física, se reconocen los beneficios de una documentación fácil de usar y actualizada. En particular, debido a la amplitud del código fuente y su crecimiento, el sistema de documentación se beneficia de la evolución paralela para brindar 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 del 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 algunos temas como las vinculaciones dinámicas de Python, se podrían realizar mejoras para lograr una documentación más completa y clara. Del mismo modo, al nuevo formato de datos RNTuple le faltan las especificaciones detalladas necesarias. Por último, a la documentación actual le faltan instructivos relacionados con ROOT 7.
Metodología: Después de consultar con Olivier, parecía que, para abordar los problemas mencionados, el enfoque principal debería ser identificar las brechas de conocimiento entre investigadores especializados y un público general, crear documentación para cerrarla, escribir una documentación más detallada sobre las vinculaciones dinámicas de Python, implementar “instructivos para el análisis moderno” para ROOT 7 y crear especificaciones técnicas detalladas para RNTuple. En esa línea, durante este proceso, la documentación podría incorporar {i>notebooks<i} de Jupyter para que las herramientas de aprendizaje interactivas y tangibles puedan ayudar a los usuarios.
Cronograma: Se estima que las etapas del proyecto son: Identificar brechas de conocimiento entre investigadores especializados y un público general (mientras lees la documentación y el código fuente actuales) → 1 a 2 semanas Crear y refactorizar la documentación para reducir esa brecha → 3 semanas Escribir una documentación más detallada de las vinculaciones dinámicas de Python → 3 semanas Implementar tutoriales para las vinculaciones dinámicas de Python → 3 semanas Implementar correctamente el proyecto para las vinculaciones dinámicas de Python → 3 semanas
Entregas y lineamiento para el éxito: Documentación unificada para el usuario sin brechas Documentación de usuario completamente actualizada para reflejar las funciones más recientes, es decir, nuevas clases derivadas Instructivos para notebooks de Jupyter