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:
- LuckInTheRain
- Nombre del proyecto:
- Documentación de ROOT: Análisis, reestructuración y reescritura
- Duración del proyecto:
- Larga duración (5 meses)
Project description
El proyecto consta de cuatro fases:
1.) Analiza la documentación actual de ROOT
El documento ROOT completo (sitio web, guía del usuario, referencia de C++, instructivos, etcétera) se analiza y verifica según los siguientes criterios: estructuración, modularización, estandarización, mecanismos de acceso, coherencia, tipos de información utilizados, preparación específica para el grupo objetivo y comprensibilidad. El objetivo es crear un concepto para la administración de la información, una matriz para la estructuración y un lineamiento para estandarizar el contenido.
2.) Definición de un método para estructurar la escritura de documentación de software con el equipo ROOT
Se presenta al equipo de ROOT DITA (Darwin Information Typing Architecture), un estándar de OASIS para la documentación de software (https://www.oasis-open.org/committees/dita/). El enfoque principal es comprender cómo estructurar el contenido específico de software y cómo se usan los tipos de información básica como “concepto”, “tarea” y “referencia” para escribir documentación sobre software.
3.) Reestructuración y reorganización de la documentación de ROOT
En función de los resultados de los dos primeros pasos, la documentación de ROOT se reestructura y se modulariza según los grupos objetivo, los roles y los casos de uso, y el contenido se asigna a los elementos y tipos de contenido correspondientes (sitio web, guía del usuario, referencia de C++, instructivos, etcétera). Dado que la información disponible es muy extensa, también se debe establecer una estructura de referencia coherente. El objetivo es brindar una descripción general integral y mostrar a los usuarios formas claras de usar ROOT para sus necesidades. Además, se proporciona una introducción compacta no orientada a la física.
4.) Reescritura de la documentación de ROOT
Las partes principales de la documentación, en especial la Guía del usuario, se reescribieron de acuerdo con el enfoque de DITA. Las reglas de estructuración y redacción se registran en una guía de estilo para garantizar la coherencia de los documentos en el futuro. El objetivo es permitir que el equipo de ROOT extienda y mantenga la documentación de ROOT en el futuro.
Cronograma estimado (5 meses):
Fase 1: Analizar la documentación actual de ROOT: 3 semanas
Fase 2: Definir un método para estructurar una documentación de software de escritura con el equipo de ROOT: 2 semanas.
Fase 3: Reestructuración y reorganización de la documentación de ROOT: 4 semanas
Fase 4: Reescribir la documentación de ROOT: 11 semanas.