Chez GitLab, nous utilisons notre plateforme pour documenter notre produit. Notre équipe de rédaction technique utilise GitLab pour planifier, créer, réviser, éditer et publier le contenu que vous pouvez consulter au sein de la documentation de GitLab. En utilisant le workflow « doc as code », nos rédacteurs sont alors capables de produire une grande quantité de contenus.
Si vous n'êtes pas encore familier avec le concept de « documentation as code », en voici une définition rapide :
La « doc as code » consiste à publier de la documentation technique en utilisant les mêmes outils et processus qu'en développement de logiciel. La documentation se place au sein du même dépôt que le code, pour permettre un contrôle des versions.
Avant d’adopter la méthodologie « documentation as code », découvrez cinq points intéressants sur la façon dont notre équipe procède.
Planifier les mises à jour des fonctionnalités et du contenu de notre documentation
Nos chefs de produit, UX Designers, ingénieurs et équipes d'assurance qualité planifient ensemble les fonctionnalités de GitLab. Lorsque vous planifiez une nouvelle version, vous utilisez probablement un tableau Kanban, ou créez un ticket avec un outil tiers.
Chez GitLab, nous utilisons des epics et un système de tickets pour planifier notre travail, ainsi que des tableaux de bord pour suivre notre progression. La transparence étant primordiale, nous rendons accessible à tous l’ensemble des informations et des discussions pour que l'équipe de rédaction technique puisse disposer d'une visibilité complète sur l'avancement des projets.
Dans le cas d'un projet de documentation de plus grande ampleur, nous effectuons l’ensemble de nos tâches depuis GitLab : suivi, modifications et résolution des tickets. De cette manière, vous pouvez visualiser l’ensemble du projet depuis un seul et même endroit et retrouver l’historique des modifications, à tout moment.
Échanger avec les équipes sur la documentation
Si vous rédigez des articles régulièrement, vous savez à quel point il peut être difficile de faire relire votre contenu par une tierce personne.
Chez GitLab, nos développeurs sont les premiers à rédiger la description des nouvelles fonctionnalités, qu’ils enregistrent dans le même dépôt que leur code. Documenter les fonctionnalités fait partie de notre definition of done (DoD) – nos critères d'accomplissement des tâches.
Ensuite, nos rédacteurs techniques révisent les contenus, y ajoutent des suggestions et les renvoient aux auteurs. Ils peuvent notamment effectuer des merge requests pour apporter des modifications.
Que la demande vienne d'un rédacteur, développeur, ingénieur, ou tout autre contributeur de la communauté, nous avons tous la possibilité de commenter facilement le travail des autres. Pour ce faire, il suffit de sélectionner le bouton « Suggestion » et d'ajouter un commentaire. Vous pouvez apporter des modifications, et l'auteur de la merge request pourra les valider ou proposer une alternative. Vous pouvez également inviter d'autres personnes à participer en mentionnant leur nom d'utilisateur. C'est transparent et participatif.
Comme la documentation est en Markdown, un langage similaire à du texte brut, il est facile de visualiser les différences entre les versions des fichiers et de voir qui a apporté telle ou telle modification.
Avec la «doc as code » , vous gagnez en efficacité et dites adieu aux versions obsolètes et aux commentaires malencontreusement effacés par une mise à jour. Si quelqu'un veut connaître les raisons d'une modification, il lui suffit de consulter l'historique de la page pour voir qui en est l'auteur, ligne par ligne.
Plus besoin de sauvegarder les versions d'un document PDF pour trouver l'origine d'une modification. Tout est dans GitLab.
Prévisualiser le contenu des documents
Chez GitLab, nos outils peuvent générer en local le contenu du site de notre documentation, mais vous pouvez aussi le visualiser directement depuis une merge request. Pour cela, il vous suffit d’ouvrir une merge request et de sélectionner «Voir l’application » pour tester et partager une idée. Le site de documentation modifié est dès lors consultable depuis une URL publique.
Vos modifications sont visibles, vous pouvez les modifier ou les valider telles quelles. Ce qui nous amène à une autre fonctionnalité utile de GitLab.
Tester chaque modification de contenu
Peut-être utilisez-vous un outil tiers pour tester les liens de vos documents ou vérifier les règles de grammaire et d'orthographe. Sachez que certains de ces outils peuvent être intégrés dans GitLab et dans le workflow de rédaction.
Chaque rédacteur dispose de nos outils installés localement, pour contrôler le document à tous les niveaux sur sa machine locale. Pour les contributeurs qui ne disposent pas de ces outils, nous exécutons pour chaque validation une version une version de nos tests dans un pipeline.
Si vous êtes un développeur sans grande expérience en rédaction, vous pourriez constater une erreur lors de la merge request à cause d'une faute de grammaire ou d’un non-respect de la charte éditoriale. Nous avons défini un ensemble de règles avec différents niveaux d'importance et effectuons des tests afin que nos contenus soient alignés avec notre guide de style et notre glossaire.
Générer le contenu HTML hébergé sur GitLab Pages
Notre pipeline CI/CD convertit et compile notre contenu Markdown en HTML. Nous hébergeons ensuite le contenu sur GitLab Pages, sur le site docs.gitlab.com.
Cette approche nous permet de mettre à jour notre documentation très régulièrement, voire même toutes les heures. Le contenu de notre documentation est donc toujours pertinent, et parfois même en avance sur la sortie de nouvelles fonctionnalités. Une situation somme toute naturelle puisque nous partageons en toute transparence notre planning de développement.
Comme vous avez pu le constater tout au long de cet article, nous apprécions vraiment travailler en doc as code. Passer à un seul outil pour gérer votre documentation peut certes demander un temps d'adaptation, mais GitLab prend en charge l'ensemble du processus de rédaction, pour toutes les personnes impliquées dans la rédaction des contenus. Et notre expertise s'appuie sur des années de pratique.
Consultez cette vidéo pour en savoir plus sur le travail de rédaction en documentation as code chez GitLab :
Vous souhaitez contribuer à notre documentation open source ? Découvrez toutes nos instructions.
