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:
- Jean
- Nom du projet:
- CERN-HSF : Documentation ROOT pour l'adoption auprès d'un public général, les liaisons Python dynamiques et les tutoriels
- Durée du projet:
- Exécution longue (5 mois)
Project description
CERN-HSF - Documentation ROOT pour l'adoption auprès d'un public général, les liaisons Python dynamiques et les tutoriels Mentor: Olivier Couet, Axel Naumann
Résumé : La documentation est essentielle pour une adoption réussie et efficace des logiciels par les utilisateurs. Une documentation utilisateur claire, précise et complète aide les utilisateurs à se familiariser avec le logiciel à mesure qu'ils s'efforcent d'atteindre leurs objectifs. À cet égard, les exemples explicites et les tutoriels sont des outils puissants qui permettent aux utilisateurs d'apprendre rapidement.
Lorsque nous examinons l'utilisation de ROOT par les physiciens, les chercheurs et les développeurs dans l'espace d'analyse et de visualisation des données pour la physique, il convient de reconnaître les avantages d'une documentation conviviale et mise à jour. En particulier, en raison de l'étendue du code source et de sa croissance, le système de documentation peut bénéficier d'une évolution parallèle afin de donner aux utilisateurs la possibilité de maximiser tout ce que ROOT a à offrir.
Résumé et analyse de la documentation actuelle Actuellement, la documentation utilisateur propose un guide qui permet aux physiciens d'adopter plus facilement ROOT par rapport à un public général. En outre, dans certains sujets tels que les liaisons Python dynamiques, des améliorations pourraient être apportées pour une documentation plus complète et plus claire. De même, le nouveau format de données RNTuple ne dispose pas des spécifications nécessaires. Enfin, la documentation actuelle ne contient pas de tutoriels liés à ROOT 7.
Méthodologie : Après avoir discuté avec Olivier, il s'est avéré que, pour résoudre les problèmes mentionnés ci-dessus, l'objectif principal était d'identifier les lacunes entre les chercheurs spécialisés et le grand public, de créer des documents pour combler cet écart, de rédiger une documentation plus détaillée sur les liaisons Python dynamiques, d'implémenter des "tutoriels pour l'analyse moderne" pour ROOT 7 et de créer des spécifications techniques détaillées pour RNTuple. Au cours de ce processus, la documentation pourrait également intégrer des notebooks Jupyter afin que des outils d'apprentissage tangibles et interactifs puissent aider les utilisateurs.
Calendrier : Les étapes du projet sont les suivantes : Identifier les lacunes entre les chercheurs spécialisés et le grand public (tout en consultant la documentation et le code source actuels) → 1 à 2 semaines Créer et refactoriser la documentation pour combler cet écart → 3 semaines Rédiger une documentation plus détaillée sur les liaisons Python dynamiques → 3 semaines Implémenter les tutoriels pour les liaisons Python dynamiques → 3 semaines Mettre en œuvre les tutoriels du projet RONT 7 → 3 semaines
Livrables et consignes pour réussir : Documentation utilisateur unifiée et sans lacune Documentation utilisateur entièrement mise à jour pour refléter les fonctionnalités les plus récentes, c'est-à-dire les nouvelles classes dérivées Tutoriels sur les notebooks Jupyter