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:
- The Linux Foundation
- Rédacteur technique:
- bore
- Nom du projet:
- Réorganiser l'hébergement et la génération de la documentation, et restructurer les pages de démarrage et les guides pour les développeurs
- Durée du projet:
- Durée standard (trois mois)
Project description
Résumé :
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 ses astuces, et de résoudre les problèmes courants rencontrés lors de son utilisation. Elle réduit également les coûts de support et fait partie de l'identité de l'entreprise et de l'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 tâches ci-dessus de manière efficace. La documentation peut jouer un rôle essentiel dans la réussite d'un produit, car une bonne communication est et restera toujours au cœur de toute entreprise ou de tout produit. Une bonne documentation ne fait que prendre cette communication et la mettre 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 compilation et d'hébergement. Dans une organisation comme AGL, qui compte plusieurs versions et une documentation très détaillée, 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 incroyablement complexe et chronophage.
État actuel :
- Le site Web de la documentation AGL est basé sur une collection de fichiers Markdown extraits de divers dépôts.
- Les pages de documentation sont actuellement hébergées dans les sources individuelles sous forme de Markdown à l'aide du moteur du projet cordova.
- Cela conduit à une configuration de 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 (Markdown [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 GitHub Pages 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 de sites Web pour la documentation d'API : 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 récupère ensuite tous les fichiers YAML du livre à partir de dépôts distants vers le modèle de site Web de documentation [https://github.com/automotive-grade-linux/docs-webtemplate]. Les fichiers YAML du livre contiennent toutes les URL des fichiers Markdown 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 de documentation AGL dans 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 facile à comprendre 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é beaucoup plus pour permettre aux développeurs de se concentrer sur la partie documentation plutôt que de maintenir le workflow de génération de la documentation et de déploiement.