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 :
- The Linux Foundation
- Rédacteur technique :
- boron
- Nom du projet :
- Rework the documentation hosting &generation and Restructure getting started pages and developer guides.
- Durée du projet :
- Durée standard (3 mois)
Description du projet
Abstraite :
Une documentation est conçue pour aider les utilisateurs finaux et les développeurs à utiliser un produit ou un service. Une bonne documentation est très importante, car elle permet aux utilisateurs d'apprendre à utiliser un logiciel, ses fonctionnalités, ses conseils et astuces, et de résoudre les problèmes courants rencontrés lors de son utilisation. Elle réduit également les coûts d'assistance et fait partie de l'identité d'entreprise et Open Source du produit : une bonne documentation est un signe de bonne santé du produit et de l'équipe de développement.
Sans une bonne documentation, un utilisateur peut ne pas savoir comment effectuer les opérations ci-dessus de manière efficace. La documentation peut jouer un rôle essentiel dans la réussite d'un produit, car une excellente communication est et sera toujours au cœur de toute entreprise ou de tout produit. Une excellente documentation prend simplement cette communication et la place dans un cadre gérable auquel tout le monde peut accéder pour réussir.
Chaque site de documentation a besoin d'un bon pipeline de workflow de création et d'hébergement. Dans une organisation comme AGL, avec plusieurs versions et une documentation très élaborée, les fichiers de documentation (markdowns) sont répartis sur plusieurs dépôts, ce qui rend leur maintenance et leur mise à jour incroyablement complexes et chronophages.
État actuel :
- Le site Web de documentation AGL est basé sur une collection de fichiers Markdown extraits de différents dépôts.
- Les pages de documentation sont actuellement hébergées dans les sources individuelles au format Markdown à l'aide du moteur du projet Cordova.
- Cela conduit à une configuration à quatre dépôts pour le processus de compilation et d'hébergement de la documentation :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : contient le modèle de site Web Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : contient des outils permettant de générer automatiquement un site Web technique à partir de fichiers Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : source (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) pour les documents généraux et les guides.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : dépôt de pages GitHub déployé pour le site de documentation [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Un outil (script) disponible dans docs-tools [https://github.com/automotive-grade-linux/docs-tools] se charge de collecter et de créer des modèles pour tous les fichiers Markdown en fonction du fichier fetched_files.yml situé dans docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Workflow actuel de génération du site Web de documentation AGL : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- Le fichier section_version.yml contient les liens vers tous les fichiers YAML du livre. Il extrait tous les fichiers YAML du livre à partir de dépôts distants vers docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Les fichiers YAML du livre contiennent toutes les URL de vos fichiers Markdown à partir du dépôt distant.
- Une fois tous les fichiers Markdown extraits, les outils génèrent le site Web de documentation AGL dans docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], qui est ensuite déployé.
- Le processus actuel de maintenance du pipeline n'est pas convivial pour les utilisateurs et les développeurs, en particulier pour les nouveaux contributeurs. Ce pipeline de workflow (de création et d'hébergement) peut être simplifié et rationalisé pour que les développeurs puissent se concentrer sur la partie documentation plutôt que sur la maintenance du workflow de génération et de déploiement de la documentation.