Documentation as Code : pourquoi et comment

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 procédure d'exploitation pas à pas) 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).

Ce que vous allez apprendre

Cette page s'adresse à une équipe qui tient sa documentation dans un wiki et se demande ce que change le passage au Docs-as-Code. Elle part des défauts structurels du wiki pour arriver à un pipeline de publication complet, puis à la migration.

• définir l'approche Docs-as-Code et ses six piliers ;
• expliquer pourquoi un wiki sans review ni historique laisse passer les erreurs ;
• décrire les étapes d'un pipeline : branche, pull request, CI, review humaine, déploiement ;
• choisir les outils de base : générateur de site statique, linter de prose, vérificateur de liens ;
• mettre en place l'approche et migrer progressivement depuis un wiki ;
• reconnaître les pièges d'adoption, à commencer par la friction.

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 d'ingénierie, les mêmes outils et la même rigueur que pour 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 leurs 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. Une pull request (PR) est une demande de fusion : on propose ses changements, d'autres les relisent (la review), puis ils rejoignent la branche principale.

• 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. La CI/CD (intégration et déploiement continus) lance ces contrôles à chaque modification proposée.

• Déployer sur un site statique généré automatiquement, pour que chaque merge (la fusion d'une PR) sur la branche principale publie instantanément la nouvelle version, sans intervention manuelle.

Ce n'est pas nouveau

L'approche Docs-as-Code existe depuis plus d'une décennie. Elle s'est popularisée avec la montée du DevOps et l'adoption massive de Git. Aujourd'hui, c'est un standard de facto pour la documentation technique.

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.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Les problèmes des wikis WYSIWYG

WYSIWYG (What You See Is What You Get) désigne l'éditeur visuel du wiki, où l'on modifie la page telle qu'elle s'affiche. Le tableau associe chaque problème de ce modèle à sa conséquence concrète ; les deux premières lignes, l'absence de review et l'historique opaque, sont celles qui coûtent le plus cher lors d'un incident.

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

Glissez pour voir

Le scénario catastrophe classique

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

1. Lundi : Alice met à jour le runbook de déploiement
2. Mardi : Bob modifie le même runbook, écrasant une partie du travail d'Alice
3. Mercredi : Charlie corrige une typo et introduit accidentellement une erreur
4. Jeudi : Incident en production. Le runbook est suivi à la lettre... mais contient l'erreur de Charlie
5. 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 ne passe plus inaperçu, car trois garde-fous s'appliquent à chaque modification : une review obligatoire avant publication, un historique Git qui dit qui a changé quoi, et une annulation possible à tout moment :

• chaque modification passe par une PR, donc par une review ;
• l'historique Git montre exactement qui a changé quoi, et pourquoi ;
• un git revert peut annuler n'importe quel changement.

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 se versionnent mal : Git ne sait pas en montrer les différences ligne à ligne)
• 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 :

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

1. É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. Elle isole la version publiée des changements en cours :

   • 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.

   # 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"

   Convention de commit

   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.

2. 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

3. 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

   Glissez pour voir

4. 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.

   Bonne pratique : le reviewer naïf

   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.

5. 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]
   
   permissions: {}
   
   jobs:
     build:
       runs-on: ubuntu-latest
       permissions:
         contents: read
       steps:
         - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
           with:
             persist-credentials: false
         - run: npm ci && npm run build
         - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
           with:
             path: dist
   
     deploy:
       needs: build
       runs-on: ubuntu-latest
       permissions:
         pages: write
         id-token: write
       environment:
         name: github-pages
       steps:
         - uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346  # v5.0.1

   Le workflow démarre sans aucun droit (permissions: {}), puis chaque job reçoit le minimum : le job build ne fait que lire le dépôt, et seul le job deploy obtient pages: write et id-token: write, les deux droits que GitHub Pages exige pour publier. persist-credentials: false empêche actions/checkout de laisser le jeton dans la configuration Git.

   Quelques minutes après le merge, 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 la review, la CI et l'historique Git empêchent 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

Glissez pour voir

Pour la collaboration

Docs-as-Code change surtout la façon de travailler à plusieurs. Les trois onglets montrent trois effets distincts : le travail asynchrone permis par les branches, l'onboarding des nouveaux arrivants, et l'ouverture aux contributions externes.

Travail asynchrone

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.

Onboarding simplifié

Les nouveaux arrivants :

• Clonent le repo
• Lisent le README
• Font leur première PR de doc

C'est le même workflow que pour le code : les mêmes commandes Git, la même pull request, aucun outil supplémentaire à apprendre.

Contributions externes

Les utilisateurs peuvent contribuer via des PR publiques. Corrections de typos, améliorations, traductions. La barrière à l'entrée est basse.

Pour la maintenabilité

La maintenabilité tient au format texte et à Git : un fichier Markdown se cherche, se déplace et se renomme avec les outils de tous les jours, et chaque opération reste tracée. Le tableau détaille cinq bénéfices concrets, de la portabilité à la gestion multi-version.

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.

Glissez pour voir

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

Glissez pour voir

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

Trois familles d'outils composent la chaîne : le générateur de site statique qui publie, les linters de prose qui contrôlent le style, et les vérificateurs de liens qui traquent les liens cassés. Aucun n'est obligatoire au premier jour, mais chacun automatise une vérification qu'un humain finit par oublier.

Générateurs de sites statiques (SSG)

Le SSG (Static Site Generator, générateur de site statique) 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

Glissez pour voir

Ce site utilise Astro/Starlight

Le site que vous lisez est construit avec Astro et le thème Starlight. Chaque page est un fichier .mdx versionné dans Git.

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 »

Glissez pour voir

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

Un lien cassé est l'erreur que les lecteurs remarquent en premier, et la plus facile à attraper automatiquement. Ces trois vérificateurs de liens se branchent dans la CI : lychee est celui que cite le pipeline décrit plus haut, htmltest contrôle le HTML généré plutôt que les sources Markdown.

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

Glissez pour voir

Mettre en place Docs-as-Code

La mise en place tient en six étapes, de la plus technique à la plus humaine. Les quatre premières (format, dépôt Git, SSG, CI) posent l'outillage ; les deux dernières, les conventions et la formation de l'équipe, conditionnent l'adoption réelle.

1. 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.

2. Initialiser le repo Git

   Soit dans le même repo que le code (monorepo), soit dans un repo dédié à la documentation.

   mkdir docs && cd docs
   git init
   echo "# Documentation" > README.md
   git add . && git commit -m "Initial commit"

3. Choisir un SSG

   Pour débuter, MkDocs Material est le plus simple :

   pip install mkdocs-material
   mkdocs new .
   mkdocs serve  # Preview local

4. Configurer le CI

   Exemple minimal pour GitHub Actions :

   .github/workflows/docs.yml

   name: Documentation
   
   on:
     pull_request:
       paths: ['docs/**', 'mkdocs.yml']
     push:
       branches: [main]
   
   permissions: {}
   
   jobs:
     lint:
       runs-on: ubuntu-latest
       permissions:
         contents: read
       steps:
         - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
           with:
             persist-credentials: false
         - run: npx markdownlint-cli 'docs/**/*.md'
   
     build:
       runs-on: ubuntu-latest
       permissions:
         contents: read
       steps:
         - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
           with:
             persist-credentials: false
         - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
           with:
             python-version: '3.12'
         - run: pip install mkdocs-material
         - run: mkdocs build --strict
         - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
           with:
             path: site
   
     deploy:
       if: github.ref == 'refs/heads/main'
       needs: [lint, build]
       runs-on: ubuntu-latest
       permissions:
         pages: write
         id-token: write
       environment:
         name: github-pages
       steps:
         - uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346  # v5.0.1

   Même principe que plus haut : lint et build ne lisent que le dépôt, et seul deploy, limité à la branche main, peut publier sur GitHub Pages. La publication passe par un artefact (upload-pages-artifact puis deploy-pages) : mkdocs gh-deploy demanderait de pousser sur une branche, donc un jeton d'écriture conservé dans le job.

5. Établir les conventions

   Documentez vos conventions dans un fichier CONTRIBUTING.md :

   • Structure des fichiers
   • Style guide
   • Processus de review
   • Templates de PR

6. 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

   Astuce : le premier commit

   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 du Docs-as-Code.

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

Stratégie progressive

1. Commencez par les nouveaux documents Tout nouveau contenu va dans le repo Git.

2. Migrez les documents critiques Runbooks, procédures d'incident, documentation API.

3. Laissez mourir le reste Les pages non consultées depuis 6 mois peuvent rester dans le wiki (en lecture seule) ou partir aux archives.

Export et conversion

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)

Glissez pour voir

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

Ne sous-estimez pas l'effort

Une migration de wiki est un projet à part entière. Prévoyez du temps pour le nettoyage, la restructuration et la formation de l'équipe. En règle générale, multipliez votre estimation initiale par 3.

Que faire du wiki pendant la transition ?

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

1. Mettez le wiki en lecture seule dès que possible
2. Ajoutez un bandeau sur chaque page wiki : « Cette documentation a migré vers [nouveau site]. Cette page n'est plus maintenue. »
3. Redirigez les URLs de l'ancien wiki vers le nouveau site
4. 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

Glissez pour voir

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.

Trois signes d'alarme trahissent une friction excessive : une typo laissée en place faute de PR, un CI rouge pour un détail, une review qui attend depuis une semaine. Dans l'équipe, ils s'entendent ainsi :

• « 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 »

Les solutions répondent à chacun de ces signes :

• 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

Glissez pour voir

Ces deux erreurs ne sont pas les seules. Le guide Anti-patterns documentation dresse la liste complète des anti-patterns documentaires, au-delà de ceux propres au Docs-as-Code.

À retenir

Docs-as-Code applique à la documentation le workflow du code (Git, branches, pull requests, CI/CD), et c'est la combinaison des six piliers qui la rend fiable, pas un outil isolé. Les points à garder en tête :

• Même workflow que le code : branche, pull request, review, CI, merge ; si vous savez coder, vous savez documenter.
• Texte brut : le Markdown vous appartient, sans enfermement chez un éditeur de wiki, et se migre quand vous voulez.
• Review obligatoire : une deuxième paire d'yeux détecte les erreurs avant vos utilisateurs, à condition de ne pas devenir une review de façade.
• Automatisation : la CI vérifie ce que les humains oublient (liens, style, build), et le merge sur la branche principale publie.
• Migration progressive : nouveaux documents d'abord, documents critiques ensuite, wiki en lecture seule puis fermé, pour garder une seule source.
• Friction maîtrisée : commits directs pour les typos, CI à niveaux d'alerte, SLA de review de 24 h.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Ressources complémentaires

Deux leçons voisines prolongent cette page : Reviews et fraîcheur montre comment garder la documentation à jour dans le temps, et Ownership et Definition of Done précise qui maintient quoi (ownership) et quand un document est terminé. Côté communauté, le guide Docs as Code de Write the Docs fait référence, et le site de Vale documente la configuration de ce linter de prose.

×

📖 Voir la documentation →