Documentation as Code : guide pratique

« Documentation as code » est une expression que l’on entend souvent. Dans sa forme la plus simple, cela signifie traiter la documentation de la même manière que le code source : stockée dans un système de contrôle de versions, écrite en texte brut, révisée via des pull requests, et construite via CI/CD. Mais il y a un écart entre l’idée et sa mise en œuvre réussie. Ce guide couvre ce qu’est docs-as-code, quelles approches existent, et où chacune atteint ses limites.

Pourquoi docs-as-code est important

Les équipes de développement disposent déjà de workflows pour gérer le changement. Le code passe par le contrôle de versions, la revue, les tests et le déploiement. La documentation, en général, non. Elle vit dans un wiki, un Google Doc ou un espace Confluence — en dehors du workflow de développement, maintenue par quiconque se souvient de la mettre à jour.

Le résultat est prévisible : la documentation dérive de la réalité. Un endpoint API est renommé, mais la page wiki référence encore l’ancien chemin. Une option de configuration est dépréciée, mais la page Notion indique qu’elle est requise. Personne ne s’en aperçoit jusqu’à ce qu’un utilisateur signale un bug.

Docs-as-code résout cela en intégrant la documentation dans le même workflow :

• Contrôle de versions — chaque modification est suivie, attribuée et réversible
• Pull requests — les modifications de documentation sont révisées aux côtés des modifications de code
• CI/CD — la documentation est construite et déployée automatiquement lors du merge
• Branching — les brouillons vivent sur des branches de fonctionnalité jusqu’à ce qu’ils soient prêts
• Blame — vous pouvez voir qui a écrit chaque ligne et quand

La communauté Write the Docs promeut cette approche depuis des années, et l’argument a été largement accepté. La partie difficile est de choisir le bon outillage.

Trois approches de docs-as-code

1. Générateurs de sites statiques

Des outils comme Docusaurus, MkDocs, Hugo et Jekyll prennent des fichiers markdown d’un dépôt git et construisent un site HTML statique. Vous éditez des fichiers .md dans votre IDE, vous commitez, poussez, et le CI construit et déploie le site.

Avantages :

• Workflow véritablement natif git — les fichiers sont simplement du markdown dans un dépôt
• Builds rapides, hébergement bon marché (Netlify, Vercel, GitHub Pages)
• Contrôle total sur les templates, le style et la structure
• Aucune dépendance runtime — le résultat est du HTML statique

Inconvénients :

• Pas d’éditeur web — tout le monde doit utiliser un éditeur de texte et git
• Pas de contrôle d’accès intégré (c’est un site statique)
• Pas de recherche sans service tiers (Algolia, Pagefind)
• Les contributeurs non techniques sont exclus
• La gestion du frontmatter devient fastidieuse à grande échelle

Exemple de workflow :

# Cloner le dépôt de documentation
git clone [email protected]:yourorg/docs.git
cd docs

# Créer une nouvelle page
cat > docs/guides/deployment.md << 'EOF'
---
title: Deployment Guide
sidebar_position: 3
---

# Deploying to Production

Follow these steps to deploy...
EOF

# Prévisualiser localement
mkdocs serve  # ou docusaurus start, hugo serve

# Commiter et pousser — le CI s'occupe du reste
git add docs/guides/deployment.md
git commit -m "docs: add deployment guide"
git push

Cela fonctionne bien pour de la documentation destinée aux développeurs où chaque contributeur est à l’aise avec git. Ça se complique lorsque des product managers, des ingénieurs support ou des rédacteurs techniques doivent contribuer.

2. Wikis et bases de connaissances

Confluence, Notion, Outline, Wiki.js et BookStack fournissent des éditeurs web avec des interfaces WYSIWYG. Le contenu vit dans une base de données, et les utilisateurs éditent via un navigateur.

Avantages :

• Faible barrière à l’entrée — tout le monde peut écrire
• Éditeurs riches avec intégration de contenus, tableaux et médias
• Collaboration en temps réel (dans certains outils)
• Recherche intégrée

Inconvénients :

• Le contenu n’est PAS dans git (ou seulement via un export unidirectionnel)
• Pas de revue par pull request pour les modifications de documentation
• Pas de branching ni de staging — les modifications sont en ligne immédiatement
• Verrouillage fournisseur — exporter depuis Confluence vers autre chose est pénible
• L’historique des versions est basique comparé à git

Ces outils optimisent la facilité d’écriture au détriment de tout ce qui fait la valeur de docs-as-code. Vous pouvez écrire facilement, mais vous perdez le contrôle de versions, la revue et la connexion avec votre codebase.

3. Plateformes de documentation avec synchronisation Git

Une catégorie plus récente : des plateformes qui combinent un éditeur web avec une véritable intégration git. L’idée est de donner aux contributeurs non techniques une interface WYSIWYG tout en conservant le contenu dans un dépôt git comme source de vérité.

C’est l’approche adoptée par DocPlatform. Les modifications faites dans l’interface web créent des commits git. Les changements poussés vers git depuis un IDE apparaissent dans l’éditeur web. Les deux directions fonctionnent — ce n’est pas un miroir unidirectionnel.

Avantages :

• Éditeur web pour les contributeurs non techniques
• Le contenu vit dans git — pull requests, branching, blame fonctionnent tous
• Recherche, contrôle d’accès et publication intégrés
• Pas d’étape de build — la documentation publiée se met à jour à la sauvegarde

Inconvénients :

• La synchronisation bidirectionnelle est difficile à maîtriser (voir Pourquoi les outils de documentation Git cassent la synchronisation)
• Moins d’options de templates que les générateurs statiques
• Nécessite un serveur (vs. hébergement statique)

Tableau comparatif

Mise en pratique : patterns efficaces

Quelle que soit l’approche choisie, ces patterns rendent docs-as-code plus efficace :

Co-localiser la documentation avec le code

Placez votre documentation dans le même dépôt que le code qu’elle décrit, ou au minimum dans la même organisation GitHub avec des références croisées. Quand un développeur modifie un endpoint API, la documentation de cet endpoint devrait être visible dans la même PR.

Utiliser le frontmatter de manière cohérente

Chaque page de documentation devrait avoir un frontmatter structuré :

---
title: "API Authentication"
description: "How to authenticate with the DocPlatform API using JWT tokens"
last_reviewed: 2026-02-15
owner: "@backend-team"
---

Les champs last_reviewed et owner ne sont pas des champs Hugo standard — ce sont des métadonnées personnalisées. Mais ils permettent de trouver facilement les pages obsolètes et de savoir à qui s’adresser.

Automatiser les vérifications de fraîcheur

Mettez en place un job CI qui signale les documents non révisés depuis 90 jours :

#!/bin/bash
find docs/ -name "*.md" -exec grep -l "last_reviewed" {} \; | while read f; do
  reviewed=$(grep "last_reviewed" "$f" | cut -d'"' -f2)
  if [[ $(date -d "$reviewed" +%s) -lt $(date -d "-90 days" +%s) ]]; then
    echo "STALE: $f (last reviewed $reviewed)"
  fi
done

Ne pas bloquer sur la perfection

Le plus grand mode d’échec de docs-as-code est de rendre la contribution trop difficile. Si votre template de PR exige une revue du guide de style, une vérification des liens, un correcteur orthographique et deux approbations — les gens arrêteront d’écrire de la documentation. Gardez la barre basse pour les modifications de contenu. Réservez la revue rigoureuse aux changements structurels.

Où se situe DocPlatform

DocPlatform est conçu pour les équipes qui veulent docs-as-code sans forcer tout le monde à passer par la ligne de commande. L’éditeur WYSIWYG gère la rédaction. Git gère le contrôle de versions. Le pattern Content Ledger gère la synchronisation bidirectionnelle pour qu’aucun côté n’écrase l’autre.

L’édition Community est gratuite et auto-hébergée — installez-la en cinq minutes avec un simple téléchargement de binaire. Si vous souhaitez un hébergement managé, les offres cloud commencent à 0 $ pour les petites équipes.

La difficulté de docs-as-code n’a jamais été la philosophie. C’était l’outillage. Les générateurs statiques fonctionnent pour les développeurs mais excluent tous les autres. Les wikis incluent tout le monde mais abandonnent le contrôle de versions. La bonne réponse est les deux : une interface de rédaction utilisable par les non-techniciens, adossée à un workflow git auquel les développeurs font confiance.