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:
- Linux Foundation
- Rédacteur technique:
- bore
- Nom du projet:
- retravailler la documentation sur l'hébergement et la génération, et restructurer les pages de démarrage et les guides du développeur ;
- Durée du projet:
- Durée standard (3 mois)
Project description
Extrait :
Une documentation est conçue pour aider les utilisateurs finaux et les développeurs à utiliser un produit ou un service. Une documentation de qualité est très importante, car elle fournit aux utilisateurs un moyen d'apprendre à utiliser un logiciel, ses fonctionnalités, des conseils et astuces, ainsi qu'à résoudre les problèmes courants rencontrés lors de l'utilisation du logiciel. Elle permet également de réduire les coûts d'assistance, et fait partie de l'identité d'entreprise et Open Source du produit. Une bonne documentation est le signe que le produit et l'équipe de développeurs sont opérationnels.
Sans une bonne documentation, un utilisateur peut ne pas savoir comment faire les choses ci-dessus de manière efficace et efficiente. Les documentations peuvent jouer un rôle central dans le succès d'un produit, car une excellente communication est et sera toujours au cœur de toute entreprise ou tout produit et 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 beaucoup de documentation élaborée, les fichiers de documentation (Markdown) sont répartis sur plusieurs dépôts, ce qui rend les tâches de maintenance et de mise à jour extrêmement 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 documents sont actuellement hébergées au sein des sources individuelles en tant que Markdown à l'aide du moteur du projet Cordov.
- Cela donne lieu à une configuration de quatre dépôts pour le processus de création 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 et les guides généraux.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : le dépôt de pages GitHub a été 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 modéliser tous les fichiers Markdown en fonction du fichier récupéré_files.yml situé dans docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Workflow actuel de génération de sites 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 des livres des dépôts distants vers le modèle docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Les fichiers YAML des livres contiennent toutes les URL de vos fichiers Markdown provenant du dépôt distant.
- Dès que tous les fichiers Markdown sont récupérés, les outils génèrent le site Web du document AGL dans les docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] qui est déployé en conséquence.
- Le processus actuel de maintenance du pipeline n'est pas convivial ni adapté aux développeurs, en particulier pour les nouveaux contributeurs. Ce pipeline de workflow (compilation et hébergement) peut être simplifié et rationalisé bien plus, pour que les développeurs puissent se concentrer sur la partie documentation plutôt que sur le workflow de génération et de déploiement de la documentation.