Exemple : un workflow docs-as-code basique

Un exemple abouti d'un changement documentaire unique, de la branche à la fusion, sous un workflow docs-as-code calqué sur une revue de code standard.

Mis à jour en septembre 2026, 2 min de lecture

Voir en Markdown

Le scénario

Un ticket de support révèle que le guide d’installation ne mentionne pas un port de pare-feu requis. Un rédacteur corrige le problème.

Le workflow

Créer une BrancheLigne de travail parallèle dans un système de gestion de versions : les modifications faites sur une branche restent isolées jusqu'à leur relecture et leur fusion dans la ligne principale, ce qui permet de faire avancer en même temps plusieurs rédacteurs, versions ou langues.Voir dans le glossaire →.
Fenêtre de terminal
```
git checkout -b docs/ajout-port-pare-feu
```
Voir utiliser les branches - une branche petite et à but unique comme celle-ci est exactement ce à quoi servent les branches.
Modifier et committer.
Fenêtre de terminal
```
# modifier installation.md
git add installation.md
git commit -m "docs: ajouter le port de pare-feu requis 8443 au guide d'installation"
```
Le message de CommitInstantané enregistré des modifications apportées à un dépôt Git, accompagné d'un auteur, d'une date et d'un message qui explique le changement. La suite des commits forme l'historique du projet, point de départ des branches et base de comparaison pour les relecteurs et les traducteurs.Voir dans le glossaire → indique ce qui a changé et, implicitement, pourquoi - un futur lecteur de git blame ne devrait pas avoir à deviner.
Pousser et ouvrir une Pull requestDemande d'intégration des modifications d'une branche dans la ligne principale, présentée sous forme de différences à relire : les relecteurs commentent, les contrôles automatisés s'exécutent et l'approbation est tracée avant la publication. GitLab parle de merge request.Voir dans le glossaire →.
Fenêtre de terminal
```
git push -u origin docs/ajout-port-pare-feu
```
La description de la PR relie le ticket de support à l’origine du correctif.
La CI s’exécute automatiquement. Le build compile le site depuis cette branche, un vérificateur de liens s’exécute sur la sortie, et un déploiement de prévisualisation est généré - voir intégrer la documentation aux processus de développement, et l’exemple de pipeline CI/CD pour le détail des étapes.
Revue. Un collègue ayant accès à la configuration réelle du pare-feu confirme le numéro de port selon la check-list de revue technique - pas selon sa mémoire de ce qu’il « devrait » être.
Fusion. Une fois la CI passée et la revue approuvée, la branche est fusionnée dans main.
Déploiement. Le même pipeline qui a construit la prévisualisation construit désormais et publie le site en production - pas d’étape de publication manuelle séparée.

Pourquoi cela fonctionne

Chaque étape automatisable (build, vérification de liens, prévisualisation, déploiement) l’est - un humain ne fait que les parties qui nécessitent un jugement : corriger et relire l’exactitude.
La PR est l’endroit unique où le changement, sa justification, ses résultats de CI et sa conversation de revue vivent ensemble - un historique utile pour quiconque demande dans un an « pourquoi le guide mentionne-t-il le port 8443 ? ».
Rien n’est parti en production sans que la CI ne passe - la même garantie que pour les changements de code.