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:
- CERN‐HSF
- Escritor técnico:
- LuckInTheRain
- Nombre del proyecto:
- Documentación raíz: 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 ROOT actual
El documento ROOT completo (sitio web, guía del usuario, referencia de C++, instructivos, etc.) 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 y comprensión específica del grupo objetivo. El objetivo es crear un concepto para la gestión de la información y una matriz para la estructuración y una pauta para estandarizar el contenido.
2.) Definir un método para estructurar una redacción de documentación de software con el equipo ROOT
DITA (Darwin Information Typing Architecture), un estándar de OASIS para la documentación de software (https://www.oasis-open.org/committees/dita/), se presenta al equipo ROOT. El enfoque principal es comprender cómo estructurar el contenido específico del software y cómo se utilizan los tipos de información básica como «concepto», «tarea» y «referencia» para escribir la documentación del software.
3.) Reestructuración y reorganización de la documentación ROOT
En función de los resultados de los dos primeros pasos, la documentación ROOT se reestructura y modulariza en función de los grupos objetivo, los roles y los casos de uso, y los contenidos se asignan a los elementos correspondientes (sitio web, guía del usuario, referencia de C++, instructivos, etc.) y tipos de contenido. 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 completa y mostrar a los usuarios formas claras de usar ROOT para satisfacer sus necesidades. Además, se proporciona una introducción compacta no relacionada con la física.
4.) Reescribe la documentación ROOT
Las partes principales de la documentación, especialmente la Guía del usuario, se reescribe de acuerdo con el enfoque de la DITA. Las reglas de estructura y escritura se registran en una Guía de estilo para garantizar la coherencia en los documentos en el futuro. El objetivo es permitir que el equipo ROOT extienda y mantenga la documentación ROOT por su cuenta en el futuro.
Programa de tiempo estimado (5 meses):
Fase 1: Analizar la documentación ROOT actual: 3 semanas
Fase 2: Definición de un método para estructurar una documentación de software de redacción con el equipo ROOT: 2 semanas
Fase 3: Reestructuración y reorganización de la documentación ROOT: 4 semanas
Fase 4: Reescritura de la documentación ROOT: 11 semanas