Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- CERN-HSF
- Rédacteur technique:
- LuckInTheRain
- Nom du projet:
- Documentation ROOT: analyse, restructuration et réécriture
- Durée du projet:
- Exécution longue (5 mois)
Project description
Le projet comprend quatre phases:
1.) Analyser la documentation ROOT actuelle
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 et compréhensibilité spécifique au groupe cible. L'objectif est de créer un concept de gestion des informations ainsi qu'une matrice de structuration et une ligne directrice pour normaliser le contenu.
2.) Définir une méthode pour structurer une documentation de logiciel de rédaction avec l’équipe ROOT
Le DITA (Darwin Information Typing Architecture) est une norme OASIS de documentation logicielle (https://www.oasis-open.org/committees/dita/) qui est présentée à l'équipe ROOT. L'objectif principal est de comprendre comment structurer le contenu spécifique au 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 du logiciel.
3.) Restructuration et réorganisation de la documentation ROOT
En fonction 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, et le contenu est attribué aux éléments correspondants (site Web, guide utilisateur, référence C++, tutoriels, etc.) et aux types de contenus correspondants. Les informations disponibles étant très complètes, une structure de référence cohérente doit également être établie. L'objectif est de fournir un aperçu complet et de montrer clairement aux utilisateurs comment utiliser ROOT pour leurs besoins. En outre, une introduction compacte non physique est fournie.
4.) Réécrire la documentation ROOT
Les principales parties de la documentation, en particulier le guide de l'utilisateur, ont été réécrites conformément à l'approche DITA. Les règles de structuration et d'écriture sont consignées dans un guide de style afin d'assurer la cohérence des documents à l'avenir. L'objectif est de permettre à l'équipe ROOT d'étendre et de maintenir elle-même la documentation ROOT à l'avenir.
Calendrier estimé (5 mois):
Phase 1: Analyser la documentation ROOT actuelle: trois semaines.
Phase 2: Définir une méthode de structuration d'une documentation logicielle de rédaction 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.