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:
- SabitaR
- Nom du projet:
- Restructuration et simplification de la documentation Allpix Squared
- Durée du projet:
- Durée standard (trois mois)
Project description
PRÉSENTATION J'ai choisi le projet Allpix Squared du CERN-HSF pour deux raisons principales:
Développement de compétences : La documentation existante de ce projet est complète et intègre plusieurs formats de contenu. L'audit et la restructuration de cette vaste suite de documents m'aideront à affiner mes compétences en architecture des informations et en rédaction. De plus, le domaine du projet (physique des particules) est nouveau pour moi. Cela me met au défi d'affiner mes compétences en interaction de développeur. Je pense que les rédacteurs techniques peuvent traiter les commentaires des développeurs et présenter des contenus utiles pour tous les niveaux d'utilisateurs, SI nous effectuons les recherches préalables requises et posons les bonnes questions. Ce projet me permettra de tester cette théorie.
Savoir-faire technique : Ce projet nécessite Hugo, un outil qui figure en tête de ma liste de choses à apprendre. J'ai hâte d'apprendre le workflow LaTeX-Markdown-Hugo-GitLab-CI.
Pendant la phase d'exploration du rédacteur technique, j'ai interagi brièvement avec les mentors du projet et je me suis familiarisé avec la structure existante de la suite de documents. J'ai également créé un site Web de démonstration (https://ap2-demo.netlify.app/) pour tester si je pouvais configurer correctement Hugo et Docsy sur mon ordinateur Windows. J'ai pu déployer le site Web sur Netlify, mais pas sur les pages Gitlab. Pour que ce projet conserve son workflow de déploiement actuel, je vais trouver un moyen de déployer le thème Docsy de Hugo sur Gitlab Pages.
RÉSULTATS ATTENDU DU PROJET - Un site Web de projet simplifié qui intègre la documentation, la référence du code, les tutoriels et les actualités. - Un manuel utilisateur restructuré et révisé, qui distingue le contenu destiné aux utilisateurs et aux développeurs, et inclut les informations manquantes auparavant - Un workflow de tutoriels à partir d'exemples de documentation d'instructions, de questions fréquentes et de problèmes courants.
OUTILS DE PROJETLa documentation actuelle d'Allpix Squared utilise LaTeX, Doxygen, pandoc et Hugo, en plus de GitLab et Gitlab CI. Les mentors du projet et moi-même avons discuté de la possibilité de convertir le contenu LaTeX en Markdown à l'aide de plug-ins MathJax. Si je réussis, le workflow de documentation impliquera Hugo, Markdown, Doxygen, git et Gitlab CI. Pour que les tutoriels restent sur le même site Web/plate-forme, j'utiliserai Hugo et Markdown. Je suis curieux de savoir s'il est possible d'utiliser Codelabs-as-a-Tool (ClaaT) pour les tutoriels. En juillet, j'espère tester le workflow ClaaT-Hugo et en discuter avec les mentors, si je suis sélectionné.
DURÉE DU PROJET Je demande à terminer le projet Allpix Squared dans les trois mois standards (14 septembre 2020 à 30 novembre 2020), au cours desquels je consacrerai environ 15 heures par semaine. Ces heures incluront les réunions avec le mentor et les e-mails associés, si nécessaire. Je respecterai également les délais de GSoD pour la création de liens au sein de la communauté et la finalisation du projet.
MISSIONS DU PROJET Voici comment j'entends implémenter les mises à jour proposées à la suite de documents Allpix Squared existante : 1. Recherche, discussion et exploration des options (17 août - 13 septembre 2020) : - Comprendre les exigences du projet - Installer le logiciel Allpix Squared pour identifier les informations manquantes, le cas échéant, dans les documents actuels. - Demandez les identifiants nécessaires. - Créer des workflows utilisateur pour différents utilisateurs d'Allpix Squared - Classer le contenu par rôle utilisateur - Vérifier les conséquences de la conversion de fichiers LaTeX en Markdown - Consolider des dépôts sources ou comprendre comment travailler avec plusieurs dépôts git - Bonus: Tester CLaaT comme option pour les tutoriels - Bonus: Rédiger un guide de style rapide/une référence de codes courts pour aider les contributeurs à gérer les documents Calendrier: Phase de consolidation de la communauté
Restructurer, examiner et améliorer le contenu (14 septembre 2020 au 19 octobre 2020) : deux tâches par semaine, environ 5 à 7 heures par tâche. Ce calendrier inclut une semaine tampon pour gérer les retards ou les problèmes inattendus.
- Examiner les contenus et les classifications d'utilisateurs existants en tenant compte des workflows utilisateur
- Définir et tester le workflow de contenu restructuré pour différents utilisateurs
- Trouver et améliorer le contenu manquant
- Convertir des fichiers LaTeX en Markdown
- Finaliser la table des matières du guide de l'utilisateur et du guide du développeur
- Générer des PDF des guides utilisateur et du développeur
- Bonus: Structurer le contenu des tutoriels à partir d'exemples et de problèmes
- Bonus: Configurez un workflow pour des exemples pratiques Délai: 5 semaines (phase de développement du document)
Créer le site Web (19 octobre - 30 novembre 2020) : une à deux tâches par semaine, environ cinq à sept heures par tâche. Ce calendrier inclut une semaine de marge pour résoudre les problèmes et affiner le résultat final.
- Comprendre et tester le workflow de publication
- Créer une structure de site Web à l'aide de Hugo et Docsy
- Découvrez comment gérer le déploiement et le workflow automatiques actuels à l'aide de Docsy.
- Extraire du contenu à partir de Doxygen
- Développer un manuel utilisateur, un guide du développeur et des tutoriels à partir de contenu LaTeX ou Markdown
- Finaliser l'apparence du site Web du projet (logo, couleurs, modèle, mise en page, liens, usabilité et CI/CD Gitlab) Délai: 6 semaines (phase de développement de la documentation)