Trop de documentations meurent dans un PDF que plus personne n’ouvre, périmé six mois après sa publication. Le mouvement « docs-as-code » propose l’inverse radical : traiter la documentation exactement comme du code source — écrite en texte brut, versionnée, revue, testée et publiée automatiquement. Le résultat n’est pas un document, c’est un produit vivant.
Les quatre principes
- Texte brut — la doc s’écrit en Markdown ou AsciiDoc, jamais dans un traitement de texte binaire.
- Versionnée dans Git — chaque changement est daté, attribuable, réversible ; on sait qui a écrit quoi et pourquoi.
- Revue par pull request — une modification de doc se relit et se valide comme une fonctionnalité, avec discussion et validation.
- Publiée en continu — un pipeline CI/CD génère et déploie le site à chaque fusion, sans intervention manuelle.
Le vrai bénéfice : une doc qui ne ment plus
Quand la documentation vit dans le même dépôt que le code, elle évolue avec lui. Un développeur qui modifie le comportement d’une API met à jour la doc dans la même pull request — et la revue peut refuser de fusionner si la doc manque. On supprime ainsi le décalage entre le produit et sa documentation, qui est la première cause de méfiance des lecteurs. Une doc en laquelle on peut avoir confiance est une doc qu’on lit.
La chaîne d’outils typique
Une mise en place courante ressemble à ceci :
- Un générateur de site statique : MkDocs (avec le thème Material), Docusaurus ou Sphinx.
- Un dépôt Git qui contient les pages Markdown à côté du code ou dans son propre projet.
- Un pipeline CI (GitHub Actions, GitLab CI) qui, à chaque fusion, construit le site et le déploie.
- Des contrôles automatiques : liens morts, orthographe, style éditorial (Vale), captures d’écran à jour.
Ce que ça change pour l’équipe
Docs-as-code fait tomber la barrière entre « ceux qui codent » et « ceux qui documentent ». Écrire de la doc devient un geste de développeur ordinaire : on ouvre une branche, on écrit, on ouvre une pull request. Les rédacteurs techniques, de leur côté, gagnent l’historique, la revue et la publication automatique. Même une petite équipe y gagne immédiatement : la doc cesse d’être une corvée annuelle pour devenir un réflexe quotidien.
Par où commencer
Inutile de tout industrialiser d’emblée. Choisissez un générateur (MkDocs Material est le plus rapide à mettre en route), mettez vos pages Markdown dans un dépôt, et branchez un déploiement automatique sur la branche principale. Ajoutez ensuite, une brique à la fois, la vérification des liens puis le contrôle de style.
À retenir
Docs-as-code n’est pas un outil, c’est une discipline : la documentation mérite les mêmes soins que le code. Versionnez-la, relisez-la en pull request, publiez-la automatiquement — et elle cessera de mentir. Une documentation vivante vaut dix manuels parfaits mais périmés.