Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- CERN-HSF
- Rédacteur technique:
- LuckInTheRain
- Nom du projet:
- Documentation ROOT: analyser, restructurer et réécrire
- Durée du projet:
- Longue durée (5 mois)
Project description
Le projet se compose de quatre phases:
1.) Analyser la documentation actuelle sur ROOT
Le document ROOT complet (site Web, guide de l'utilisateur, documentation de référence C++, tutoriels, etc.) est analysé et vérifié selon les critères suivants: structuration, modularisation, standardisation, mécanismes d'accès, cohérence, types d'informations utilisés, préparation spécifique au groupe cible et compréhension. L'objectif est de créer un concept de gestion des informations, une matrice de structuration et des consignes de normalisation du contenu.
2.) Définir une méthode de structuration de la documentation logicielle avec l'équipe ROOT
DITA (Darwin Information Typing Architecture), une norme OASIS pour la documentation logicielle (https://www.oasis-open.org/committees/dita/) est présentée à l'équipe ROOT. L'objectif principal est de comprendre comment structurer un contenu spécifique à un logiciel et comment les types d'informations élémentaires tels que "concept", "tâche" et "référence" sont utilisés pour rédiger la documentation logicielle.
3.) Restructuration et réorganisation de la documentation ROOT
Sur la base des résultats des deux premières étapes, la documentation ROOT est restructurée et modularisée en fonction des groupes cibles, des rôles et des cas d'utilisation. Le contenu est attribué aux éléments correspondants (site Web, guide de l'utilisateur, référence C++, tutoriels, etc.) et aux types de contenus correspondants. Étant donné que les informations disponibles sont très nombreuses, une structure de référence cohérente doit également être établie. L'objectif est de fournir une présentation complète et de montrer aux utilisateurs comment utiliser ROOT pour répondre à leurs besoins. De plus, une introduction compacte non axée sur la physique est fournie.
4.) Réécriture de la documentation ROOT
Les principales parties de la documentation, en particulier le guide de l'utilisateur, sont réécrites conformément à l'approche DITA. Les règles de structuration et d'écriture sont consignées dans un guide de style afin de garantir la cohérence des documents à l'avenir. L'objectif est de permettre à l'équipe ROOT d'étendre et de gérer elle-même la documentation ROOT à l'avenir.
Calendrier estimé (sur cinq mois):
Phase 1: Analyse de la documentation ROOT actuelle: trois semaines.
Phase 2: Définition d'une méthode pour structurer la rédaction d'une documentation logicielle avec l'équipe ROOT: 2 semaines
Phase 3: Restructuration et réorganisation de la documentation ROOT: 4 semaines.
Phase 4: Réécriture de la documentation ROOT: 11 semaines.