Documentation as Code : pourquoi et comment

Mise à jour : 31/12/2025

Votre wiki Confluence est devenu un cimetière de pages. Personne ne sait quelle version est la bonne. Quelqu’un a modifié le runbook critique la semaine dernière, mais impossible de savoir qui et pourquoi. Une erreur s’est glissée dans la procédure de déploiement et personne ne s’en est aperçu avant l’incident de production.

Cette situation vous parle ? C’est le quotidien des équipes qui n’ont pas adopté l’approche Documentation as Code (ou Docs-as-Code).

Qu’est-ce que Documentation as Code ?

L’idée fondamentale est simple : traiter la documentation exactement comme du code source. Autrement dit, appliquer à vos documents les mêmes pratiques, outils et rigueur que vous appliquez à votre code de production.

Pourquoi cette approche ? Parce que le code et la documentation partagent les mêmes défis : ils doivent être maintenus, versionnés, relus, et ils évoluent constamment. Les développeurs ont passé des décennies à perfectionner leurs outils et workflows. Docs-as-Code consiste simplement à réutiliser cette expertise pour la documentation.

Concrètement, cela signifie :

Écrire en format texte (Markdown, AsciiDoc, reStructuredText) — des formats que n’importe quel éditeur peut ouvrir, que Git peut versionner efficacement, et qui restent lisibles même sans outil spécialisé.
Stocker dans un système de versioning (Git) — pour avoir un historique complet de chaque modification, pouvoir revenir en arrière, et travailler en parallèle sur plusieurs changements.
Passer par des pull requests et des reviews — pour que chaque modification soit examinée par au moins une autre personne avant d’être publiée, exactement comme pour le code.
Valider automatiquement avec des pipelines CI/CD — pour détecter les erreurs (liens cassés, fautes de style, problèmes de syntaxe) avant qu’elles n’atteignent les utilisateurs.
Déployer sur un site statique généré automatiquement — pour que chaque merge sur la branche principale publie instantanément la nouvelle version, sans intervention manuelle.

Pourquoi les wikis traditionnels échouent

Avant d’expliquer les bénéfices de Docs-as-Code, prenons le temps de comprendre pourquoi les wikis traditionnels — Confluence, SharePoint, Notion, MediaWiki — finissent presque toujours par devenir des « cimetières de documentation ».

Ce n’est pas que ces outils soient mauvais. Ils excellent pour certains usages (notes de réunion, brainstorming, documentation non technique). Mais pour la documentation technique qui doit rester fiable dans le temps, leur modèle présente des failles structurelles.

Comparaison wiki traditionnel vs Docs-as-Code

Les problèmes des wikis WYSIWYG

Problème	Conséquence
Pas de review obligatoire	N’importe qui peut publier une erreur instantanément
Historique opaque	Qui a modifié quoi ? Pourquoi ? Impossible à tracer
Format propriétaire	Données enfermées, migration difficile
Pas de branches	Impossible de préparer une mise à jour complexe
Pas de CI/CD	Aucune validation automatique
Éditeur web uniquement	Pas de travail hors-ligne, pas d’éditeur de votre choix

Le scénario catastrophe classique

Voici un scénario que vous avez peut-être vécu :

Lundi : Alice met à jour le runbook de déploiement
Mardi : Bob modifie le même runbook, écrasant une partie du travail d’Alice
Mercredi : Charlie corrige une typo et introduit accidentellement une erreur
Jeudi : Incident en production. Le runbook est suivi à la lettre… mais contient l’erreur de Charlie
Vendredi : Réunion post-mortem. Impossible de savoir précisément ce qui a changé, quand, et pourquoi

Avec Docs-as-Code, ce scénario est impossible :

Chaque modification passe par une PR → review obligatoire
L’historique Git montre exactement qui a changé quoi
Un git revert peut annuler n’importe quel changement

L’analogie du code sans Git

Imaginez développer du code comme on fait de la doc dans un wiki :

Pratique wiki	Équivalent code (absurde)
Modifier et sauvegarder directement	Éditer en production
Pas de review	Déployer sans code review
Historique limité	Pas de commit history
Format propriétaire	Code dans un format binaire

Personne n’accepterait de coder ainsi. Pourquoi accepter de documenter ainsi ?

La réponse est souvent : « Parce que c’est comme ça qu’on a toujours fait » ou « Les non-développeurs ne connaissent pas Git ». Ces arguments ne tiennent plus. Les outils modernes rendent Docs-as-Code accessible à tous, et le coût de la documentation défaillante dépasse largement l’effort d’apprentissage.

Les six piliers de Docs-as-Code

Docs-as-Code repose sur six principes fondamentaux. Chacun apporte une valeur spécifique, et c’est leur combinaison qui crée un système robuste.

1. Format texte

Markdown, MDX, AsciiDoc. Lisible par les humains, versionable par Git.

2. Versioning Git

Historique complet, branches, tags. Qui a changé quoi, quand, pourquoi.

3. Pull Requests

Proposer des changements. Discuter. Approuver. Puis merger.

4. Reviews

Au moins une personne valide avant publication. Comme pour le code.

5. CI/CD

Tests automatiques : liens cassés, orthographe, style, build.

6. Déploiement auto

Merge = publication. Pas d’étape manuelle. Pas d’oubli.

Pourquoi ces six piliers fonctionnent ensemble

Chaque pilier renforce les autres :

Le format texte permet le versioning Git (les fichiers binaires ne se versionnent pas bien)
Le versioning Git permet les branches et donc les Pull Requests
Les Pull Requests créent un espace naturel pour les reviews
Les reviews sont renforcées par les vérifications CI/CD
Le CI/CD permet le déploiement automatique

Retirer un pilier affaiblit l’ensemble. Par exemple, utiliser Git sans PR ni review revient à perdre la moitié des bénéfices.

Le pipeline Docs-as-Code en détail

Voici à quoi ressemble un pipeline typique, du moment où vous commencez à éditer jusqu’à la publication :

Pipeline Docs-as-Code : sources, linting, build, deploy

Écriture en Markdown

L’auteur rédige ou modifie un fichier .md ou .mdx dans son éditeur préféré. C’est l’un des grands avantages de Docs-as-Code : vous n’êtes pas coincé dans un éditeur web. VS Code avec ses extensions Markdown, Vim pour les puristes, ou même Obsidian pour ceux qui préfèrent une interface graphique — tout fonctionne.

Le travail se fait dans une branche Git dédiée, jamais directement sur main. Cela permet de :
- Travailler sans impacter la version publiée
- Préparer des changements complexes sur plusieurs jours
- Avoir plusieurs personnes travaillant en parallèle sur des sujets différents
Terminal window
```
# Créer une branche pour votre modification
git checkout -b docs/update-runbook-api

# Éditer le fichier avec votre éditeur favori
# ... modifications ...

# Commiter avec un message clair
git add docs/runbook-api.md
git commit -m "docs: mise à jour procédure redémarrage API

- Ajout des nouvelles commandes kubectl
- Mise à jour des URLs du monitoring
- Correction de la section rollback"
```
Utilisez des messages de commit clairs et descriptifs. Le préfixe docs: permet de filtrer facilement l’historique. Le corps du message détaille les changements pour faciliter les reviews.

Pull Request

L’auteur ouvre une PR (Pull Request ou Merge Request selon la plateforme). La PR décrit les changements et leur contexte.

## Description
Mise à jour du runbook suite à la migration vers Kubernetes.

## Changements
- Nouvelles commandes kubectl
- Suppression des références à l'ancien serveur
- Ajout de la section monitoring

Validation automatique (CI)

Le pipeline CI/CD s’exécute automatiquement et vérifie :

Vérification	Outil	Ce qui est testé
Syntaxe Markdown	markdownlint	Structure, formatage
Style rédactionnel	Vale	Orthographe, ton, jargon
Liens	lychee	Liens cassés (internes et externes)
Build	Astro/Hugo/MkDocs	Le site compile sans erreur

Review humaine

C’est l’étape la plus importante. Un ou plusieurs reviewers examinent les changements avec un regard neuf. Contrairement à l’auteur qui connaît le contexte par cœur, le reviewer voit le document comme le verra un utilisateur.

Les questions à se poser en tant que reviewer :
- Exactitude technique : les informations sont-elles correctes ?
- Clarté : quelqu’un qui ne connaît pas le sujet comprendra-t-il ?
- Complétude : manque-t-il des étapes, des prérequis, des avertissements ?
- Style : le ton est-il cohérent avec le reste de la documentation ?
- Testabilité : peut-on suivre cette procédure de A à Z ?
Les reviewers laissent des commentaires directement sur les lignes concernées. L’auteur répond, discute, et pousse des corrections. Ce dialogue améliore la qualité finale bien au-delà de ce qu’une personne seule pourrait produire.

Idéalement, au moins un reviewer devrait être quelqu’un qui ne connaît pas le sujet en profondeur. Si cette personne comprend la procédure, vos utilisateurs la comprendront aussi.

Merge et déploiement

Une fois la PR approuvée et les checks CI passés, elle est mergée. Le pipeline de déploiement se déclenche automatiquement :

# Exemple GitHub Actions
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: actions/deploy-pages@v4

Quelques minutes plus tard, la documentation est en ligne.

Bénéfices concrets

Passons des principes à la pratique. Voici ce que Docs-as-Code change concrètement au quotidien.

Pour la qualité

La qualité de la documentation s’améliore mécaniquement, pas parce que les auteurs deviennent meilleurs, mais parce que le système empêche les erreurs de se propager.

Avant (wiki)	Après (Docs-as-Code)
Erreurs publiées immédiatement	Review obligatoire avant publication
Liens cassés découverts par les utilisateurs	Détectés automatiquement en CI
Style incohérent	Style guide appliqué par linter
« Qui a cassé la doc ? »	`git blame` + historique complet
Procédures non testées	PR encourage le test avant merge
Typos qui persistent	Faciles à corriger via quick PR

Pour la collaboration

Les contributeurs travaillent chacun sur leur branche. Pas de conflits d’édition simultanée. Les discussions se font dans les PR, de manière asynchrone.

Un développeur en Australie peut proposer une modification que l’équipe européenne reviewera le lendemain matin.

Pour la maintenabilité

Aspect	Bénéfice
Portabilité	Markdown = texte brut. Migrez où vous voulez.
Backup	Git = distribué. Chaque clone est une sauvegarde.
Recherche	`grep`, `ripgrep`, recherche IDE. Instantané.
Refactoring	Renommez, déplacez, réorganisez. Git trace tout.
Multi-version	Tags et branches pour chaque version produit.

Pour la résilience

Un aspect souvent négligé : la résilience face aux incidents et aux départs.

Situation	Avec wiki	Avec Docs-as-Code
Serveur wiki HS	Pas de doc accessible	Clone local sur chaque poste
Corruption de données	Restauration complexe	`git clone` depuis n’importe quel remote
Départ d’un expert	Connaissances perdues	Historique des contributions préservé
Besoin d’audit	Export manuel, formatage cassé	`git log` + diff natif

Chaque développeur qui a cloné le repo possède une copie complète de l’historique. Même si GitHub/GitLab disparaît, la documentation survit.

Outils de l’écosystème

Générateurs de sites statiques (SSG)

Le SSG (Static Site Generator) est le cœur de votre pipeline. Il prend vos fichiers Markdown et les transforme en un site web complet, avec navigation, recherche, et mise en forme professionnelle.

Le choix du SSG dépend de votre écosystème technique et de vos besoins :

Outil	Langage	Points forts	Idéal pour
Astro/Starlight	JavaScript	Rapide, moderne, excellent DX	Doc technique moderne
MkDocs Material	Python	Simple, beau thème par défaut	Démarrage rapide
Docusaurus	JavaScript	Versioning intégré, i18n	Doc produit multi-versions
Hugo	Go	Très rapide, pas de dépendances	Gros volumes, sites rapides
Sphinx	Python	Standard pour Python, autodoc	Doc API Python
GitBook	SaaS	Pas d’infra à gérer	Équipes non-techniques

Linters pour la prose

Les linters vérifient automatiquement la qualité de votre documentation. Ils détectent les problèmes que les humains manquent facilement : incohérences de style, jargon non expliqué, phrases trop longues, voix passive excessive.

Outil	Rôle	Exemple de règle
Vale	Linter de prose configurable	« Éviter simply, just, easy »
markdownlint	Validation syntaxe Markdown	« Headers doivent être séquentiels »
textlint	Linter extensible pour texte	« Phrases < 25 mots »
write-good	Suggestions de style (anglais)	« Éviter la voix passive »

Exemple de configuration Vale

Vale est particulièrement puissant car il permet d’appliquer des style guides reconnus (Microsoft, Google) ou de créer vos propres règles.

# .vale.ini - Configuration racine
StylesPath = .vale/styles
MinAlertLevel = suggestion

# Packages à télécharger : vale sync
Packages = Microsoft, write-good

[*.md]
BasedOnStyles = Vale, Microsoft, write-good

# Désactiver certaines règles trop strictes
Microsoft.HeadingAcronyms = NO
write-good.Passive = suggestion  # Warning au lieu d'erreur

# .vale/styles/MonEquipe/Jargon.yml - Règle personnalisée
extends: existence
message: "Évitez le jargon '%s'. Expliquez ou reformulez."
level: warning
tokens:
  - leverage
  - synergy
  - paradigm
  - deep dive

Vérification de liens

Outil	Description
lychee	Rapide, écrit en Rust
markdown-link-check	Simple, Node.js
htmltest	Vérifie le HTML généré

Mettre en place Docs-as-Code

Choisir le format

Markdown est le choix par défaut. MDX si vous avez besoin de composants interactifs. AsciiDoc pour des documents très structurés.
Initialiser le repo Git

Soit dans le même repo que le code (monorepo), soit dans un repo dédié à la documentation.
Terminal window
```
mkdir docs && cd docs
git init
echo "# Documentation" > README.md
git add . && git commit -m "Initial commit"
```
Choisir un SSG

Pour débuter, MkDocs Material est le plus simple :
Terminal window
```
pip install mkdocs-material
mkdocs new .
mkdocs serve  # Preview local
```

Configurer le CI

Exemple minimal pour GitHub Actions :

name: Documentation

on:
  pull_request:
    paths: ['docs/**', 'mkdocs.yml']
  push:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx markdownlint-cli docs/**/*.md

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material
      - run: mkdocs build --strict

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: [lint, build]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Établir les conventions

Documentez vos conventions dans un fichier CONTRIBUTING.md :
- Structure des fichiers
- Style guide
- Processus de review
- Templates de PR
Former l’équipe

La courbe d’apprentissage est faible si l’équipe connaît déjà Git. Prévoyez une session de 30-60 minutes couvrant :
- Le « pourquoi » : expliquez les problèmes que Docs-as-Code résout
- Le workflow : branche → édition → commit → PR → review → merge
- La pratique : faites une PR ensemble, du début à la fin
- Le CI : montrez ce qui se passe quand le pipeline détecte un problème
- Les ressources : où trouver de l’aide, qui contacter
Demandez à chaque membre de l’équipe de faire une modification triviale (corriger une typo, améliorer une phrase) dans les 48h suivant la formation. Rien de tel que la pratique pour ancrer l’apprentissage.

Gérer la transition depuis un wiki

Si vous avez un wiki existant avec des années de contenu, la tentation est de tout migrer d’un coup. Résistez. Une migration « big bang » est le meilleur moyen de créer du chaos et de dégoûter l’équipe.

Adoptez plutôt une stratégie progressive qui minimise les risques et permet d’ajuster en cours de route.

Stratégie progressive
Export et conversion

Commencez par les nouveaux documents Tout nouveau contenu va dans le repo Git.
Migrez les documents critiques Runbooks, procédures d’incident, documentation API.
Laissez mourir le reste Les pages non consultées depuis 6 mois peuvent rester dans le wiki (en lecture seule) ou être archivées.

La plupart des wikis permettent d’exporter en HTML ou XML. Des outils de conversion existent :

Wiki source	Outil de conversion
Confluence	confluence-to-markdown (npm)
MediaWiki	pandoc
Notion	notion-to-md
Google Docs	docs-to-markdown (add-on)

Attendez-vous à du nettoyage manuel après conversion.

Que faire du wiki pendant la transition ?

Pendant la période de transition, vous aurez deux sources. Pour éviter la confusion :

Mettez le wiki en lecture seule dès que possible
Ajoutez un bandeau sur chaque page wiki : « Cette documentation a migré vers [nouveau site]. Cette page n’est plus maintenue. »
Redirigez les URLs de l’ancien wiki vers le nouveau site
Fixez une date de fermeture du wiki et communiquez-la

Pièges courants et solutions

Même avec la meilleure volonté, certains pièges guettent les équipes qui adoptent Docs-as-Code. Voici les plus fréquents et comment les éviter.

Piège	Problème	Solution
Trop de friction	PR pour une typo = décourageant	Autoriser les commits directs pour typos mineures
Reviews qui traînent	Doc jamais publiée	SLA de review (24h max) + rotation
CI trop stricte	Bloqué par des warnings mineurs	Niveaux d’alerte (error vs warning)
Pas de preview	Impossible de voir le rendu	Deploy preview sur chaque PR
Monorepo ingérable	Doc noyée dans le code	Dossier `/docs` dédié et bien structuré
Markdown trop limité	Besoin de composants riches	MDX, Astro, ou SSG avec extensions

Focus : le problème de la friction

Le piège le plus insidieux est la friction excessive. Si contribuer à la doc demande plus d’effort qu’avant, les gens arrêteront de contribuer.

Signes d’alarme :

« J’aurais bien corrigé cette typo mais flemme de faire une PR »
« Le CI est rouge pour un truc mineur, je laisse tomber »
« Ma PR attend une review depuis une semaine »

Solutions :

Commits directs autorisés pour les typos et corrections mineures
CI avec niveaux : warnings vs erreurs bloquantes
SLA de review : 24h max, rotation des reviewers
Templates de PR pré-remplis pour réduire l’effort

Anti-patterns à éviter

Deux erreurs reviennent systématiquement lors de l’adoption de Docs-as-Code :

Anti-pattern	Pourquoi c’est un problème	Alternative
Wiki ET Git en parallèle	Deux sources de vérité = personne ne sait où est la bonne version	Une seule source (Git), wiki en lecture seule puis fermé
Reviews de façade	Approuver sans lire revient à ne pas avoir de review	Exiger un commentaire substantif, rotation des reviewers

Pour une liste complète des anti-patterns documentaires (pas seulement liés à Docs-as-Code), consultez le guide dédié :

Anti-patterns documentation Les erreurs classiques à éviter absolument dans votre documentation

À retenir

Même workflow que le code

Git, branches, PR, reviews, CI/CD. Si vous savez coder, vous savez documenter.

Texte brut = liberté

Markdown vous appartient. Pas de vendor lock-in. Migrez quand vous voulez.

Review = qualité

Une deuxième paire d’yeux détecte les erreurs avant vos utilisateurs.

Automatisation = fiabilité

Le CI vérifie ce que les humains oublient : liens, style, build.

Ressources complémentaires

Reviews et fraîcheur Comment maintenir la documentation à jour

Ownership et Definition of Done Qui maintient quoi et quand un document est terminé

Write the Docs - Docs as Code Guide complet de la communauté Write the Docs

Vale - Prose Linter Linter configurable pour la documentation