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:
- SabitaR
- Nom du projet:
- Restructuration et simplification de la documentation d'Allpix Square
- Durée du projet:
- Durée standard (3 mois)
Project description
PRÉSENTATION J'ai choisi le projet Allpix Squared du CERN-HSF pour deux raisons principales:
Développement des 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 mon architecture des informations et mes compétences en rédaction. De plus, le domaine du projet (physique des particules !) est nouveau pour moi. Cela me met au défi de perfectionner mes compétences en matière d'interaction avec les développeurs. Je pense que les rédacteurs techniques peuvent traiter les informations fournies par les développeurs et présenter du contenu utile pour tous les niveaux d'utilisateurs, SI nous effectuons les recherches nécessaires 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 haut de ma liste de choses à apprendre. J'ai hâte de découvrir le workflow LaTeX-Markdown-Hugo-GitLab-CI.
Pendant la phase d'exploration des rédacteurs techniques, j'ai brièvement interagi 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 peux configurer Hugo et Docsy correctement sur mon ordinateur Windows. J'ai pu déployer le site Web sur Netlify, mais pas sur des pages Gitlab. Pour que ce projet conserve son workflow actuel, je vais trouver un moyen de déployer le thème Hugo Docsy sur des pages Gitlab.
RÉSULTATS DU PROJET ATTENDU - Un site Web de projet simplifié qui intègre de la documentation, des références de code, des tutoriels et des actualités. - Un manuel utilisateur restructuré et révisé qui distingue le contenu destiné aux utilisateurs et les développeurs, et qui inclut des informations manquantes. - Un flux de travail de tutoriels à partir d'exemples disponibles de documentation d'utilisation, de questions fréquentes et de problèmes courants.
OUTILS DE PROJET La documentation actuelle d'Allpix Squad utilise LaTeX, Doxygen, pandoc et Hugo, en plus de GitLab et Gitlab CI. Les mentors du projet et moi avons discuté de la possibilité de déplacer du contenu de LaTeX vers Markdown avec les plug-ins MathJax. Si je réussis, le workflow de documentation impliquera Hugo, Markdown, Doxygen, git et Gitlab CI. Pour conserver les tutoriels sur le même site Web/la même plateforme, j'utiliserai Hugo et Markdown. J'aimerais savoir s'il est possible d'utiliser Codelabs-as-a-Tool (ClaaT) pour les tutoriels. En juillet, j'espère tester le flux de travail ClaaT-Hugo et en discuter avec les mentors, s'ils sont sélectionnés.
DURÉE DU PROJET Je vous demande de terminer le projet Allpix Square sur la période standard de trois mois (du 14 septembre 2020 au 30 novembre 2020), pendant laquelle je passerai environ 15 heures par semaine. Ces heures comprendront des réunions de mentorat et des e-mails connexes, si nécessaire. Je respecterai également les délais GSoD pour la cohésion de la communauté et la finalisation du projet.
TÂCHES RELATIVES AU PROJET Voici comment j'envisage d'implémenter les mises à jour que j'ai proposées pour la suite de documents Allpix Squared existante : 1. Faire des recherches, discuter et explorer les options (du 17 août au 13 septembre 2020) : - Comprendre les exigences du projet - Installer le logiciel Allpix Square pour identifier les éventuelles informations manquantes dans les documents actuels. - Demandez les identifiants nécessaires. - Créer des workflows utilisateur pour différents utilisateurs d'Allpix Squared - Classer du contenu par rôle utilisateur - Vérifier les implications de la conversion de fichiers LaTeX en Markdown - Consolider les dépôts sources ou comprendre comment utiliser plusieurs dépôts Git
Restructurez, révisez et améliorez le contenu (14 septembre – 19 octobre 2020) : Deux tâches par semaine, environ 5 à 7 heures par tâche. Ce calendrier comprend une semaine tampon pour gérer les retards ou les problèmes imprévus.
- Examinez les contenus existants et les classifications d'utilisateurs en tenant compte des workflows
- Décrire et tester un workflow de contenu restructuré pour différents utilisateurs
- Rechercher et améliorer le contenu manquant
- Convertir les fichiers LaTeX en Markdown
- Finaliser le guide de l'utilisateur et la table des matières du guide du développeur
- Générer des PDF contenant les guides de l'utilisateur et du développeur
- Bonus: structurer le contenu des tutoriels à partir d'exemples et de problèmes
- Bonus: configurer un workflow de tutoriel pour des exemples d'utilisation Calendrier: 5 semaines (phase de développement du document)
Création du site Web (du 19 octobre au 30 novembre 2020) : 1 à 2 tâches par semaine, environ 5 à 7 heures par tâche. Ce calendrier comprend une semaine tampon pour résoudre les problèmes et ajuster le résultat final.
- Comprendre et tester le workflow de publication
- Créer une structure de site Web à l'aide de Hugo et Docsy
- Tester comment maintenir le déploiement et le workflow automatiques actuels à l'aide de Docsy
- Extraire le contenu de Doxygen
- Développer un manuel utilisateur, un guide du développeur et des tutoriels à partir de contenus LaTex ou Markdown
- Finaliser l'aspect général du site Web du projet (logo, couleurs, modèle, mise en page, liens, facilité d'utilisation et CI/CD Gitlab) Échéancier: 6 semaines (phase de développement du document)