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:
- bore
- Nom du projet:
- Retravailler la documentation sur l'hébergement et la génération de la documentation, 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 bonne documentation est très importante, car elle offre aux utilisateurs un moyen d’apprendre à utiliser un logiciel, ses fonctionnalités, des conseils et astuces, et également à 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 documentation de qualité est un signe de l'intégrité du produit et de l'équipe de développeurs.
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 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, qui dispose de plusieurs versions et d'une grande documentation laborieuse, les fichiers de documentation (Markdown) sont répartis sur plusieurs dépôts, ce qui rend la tâche de maintenance et de mise à jour extrêmement complexe et chronophage.
État actuel :
- Le site Web de la documentation AGL est basé sur une collection de fichiers Markdown extraits de différents référentiels.
- Les pages de document sont actuellement hébergées au niveau des sources individuelles en tant que Markdown à l'aide du moteur du projet Cordov.
- Quatre dépôts sont alors configurés 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 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] prend en charge la collecte et la modélisation de tous les fichiers Markdown en fonction du fichier fetch_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 des livres. Il récupère tous les fichiers YAML des livres à partir de dépôts distants vers le modèle docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Les fichiers YAML des livres contiennent l'URL complète de vos fichiers Markdown à partir du dépôt distant.
- Dès que tous les fichiers Markdown sont récupérés, les outils procèdent à la génération du 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 adapté aux utilisateurs ni aux développeurs, en particulier pour les nouveaux contributeurs. Ce pipeline de workflow (de création et d'hébergement) peut être simplifié et rationalisé bien plus pour que les développeurs puissent se concentrer sur la partie documentation au lieu de gérer le workflow de génération et de déploiement de la documentation.