Dans cet article :
- Documentation-Driven Développement (DocDD)
- ADR : Architecture Decision Record
- On met quoi dans la Definition Of Done ?
- Et on a plein d’outils Docs as code facilement
- Des guides utiles aux devs et aux IA
- Conclusion : la documentation technique, c’est comme les chocapics. C’est avant et pas après le lait.
“Elle est où la documentation technique ? La documentation, c’est le code. Y’a pas de cahier des charges. On est en agile.”
Ensuite, six mois plus tard, je découvre une dépendance maison mal implémentée. Elle provoque des crashs quotidiens en prod. En effet, impossible de livrer un correctif. La version avait passé trois semaines en recette. Donc elle devait partir en prod, bugs compris.
Cependant, il existait bien un Confluence. C’était un fourre-tout obsolète, sans parties prenantes impliquées. Pourtant, la plupart des devs avaient déjà quitté l’équipe.
Dans les startups des années 2010, la documentation technique passait après tout. En effet, on s’en souciait surtout pour le CIR ou le CII.
Aujourd’hui, sur mes side-projects, la documentation développeur passe en premier. Par ailleurs, le code est souvent généré par un agent IA. Donc je garde du temps pour la documentation technique et pour moi. Ensuite, je travaille par sessions de trente minutes. Ainsi, je peux lever les mains du clavier et reprendre vite. Enfin, chaque début de session ajoute la doc au contexte de l’agent.
J’ai donc interrogé des spécialistes de la documentation technique. On va commencer par quelques bonnes pratiques faciles à adopter dès aujourd’hui. Au résultat, vous améliorerez la developer expérience et la documentation développeur. De plus, vous utiliserez comme levier les outils docs as code. Par ailleurs, vous soignerez la documentation API et le guide de contribution. Enfin, vous intégrerez la definition of done documentation dans le flux de production.
Documentation-Driven Development (DocDD)
Je ne prétends pas lancer un nouveau standard.
Mais dès mon échange avec Pierre Wizla (Lead Tech Writer chez Strapi), le constat est tombé : « Même avec une équipe doc dédiée, la communication peut foirer : “On sort ça dans une heure, vous pouvez écrire la doc ?” »
Autrement dit, la documentation développeur passe après.
Le souci, c’est qu’elle n’entre pas dans la Definition of Done (DoD).
Par conséquent, la feature est expédiée.
Et toute l’équipe perd du temps. Les contributeurs aussi. La vélocité s’effondre.
C’est là que le DocDD peut changer la donne.
Il part d’une idée simple : la documentation technique est le contrat qui précède le code, et l’artefact qui l’accompagne.
Tant qu’elle n’est pas dans la DoD, elle reste optionnelle.
Et je me reconnais dans ce modèle.
Les vrais problèmes de conception ne devraient pas surgir en code review.
Au contraire, ils doivent remonter plus tôt, lors du Backlog Refinement, puis être fixés dans un ADR.
Un cycle DocDD tient en trois temps :
- D’abord, écrire l’ADR (décision, alternatives, conséquences).
- Ensuite, coder selon le contrat (interfaces + tests).
- Enfin, mettre à jour la doc (README / CHANGELOG / Doc API) avant de pousser.
Au fond, ce n’est pas si éloigné du Test-Driven Development.
Dans les deux cas, on formalise l’intention avant d’écrire la première ligne.
Alors si vous en êtes là… pourquoi ne pas écrire les tests d’abord ? 😀
ADR : Architecture Decision Record
Tu te rappelles cette discussion à la machine à café avec le ou la Tech Lead ? On avait parlé d’une feature un peu touchy, il avait partagé ses intuitions… et tout le monde les a prises pour des directives.
Cette conversation n’existe que dans ta tête. Au moment de la PR, elle n’est nulle part.
Un Architecture Decision Record sert à rendre explicite cette décision, pour toi demain et pour l’équipe. Il aide aussi à jeter du code quand il le faut.
Exemple personnel : j’ai bricolé une journée avec transformer.js pour un POC d’enregistreur vocal en temps réel. En vanilla.js, c’est devenu un spaghetti plein d’effets de bord. J’ai décidé de tout jeter et de repartir sur une machine à états. Avant d’effacer, j’ai posé un ADR : ce qui a été tenté, ce qui marche, ce qui bloque, ce que je vais changer. Puis j’ai supprimé le code mort — sans perdre la mémoire de la décision.
Comment écrire un ADR en une page (modèle simple) ?
Que peut-on lire dans : /docs/adr/ADR-0001-titre-court.md
# ADR-<numéro> — <Titre court et concret>
Date: YYYY-MM-DD
Status: proposed | accepted | superseded | deprecated
Owner: @handle
Related: Issue #…, PR #…, RFC/Doc …
## Contexte
- Problème, contraintes, objectifs (DX, perf, sécurité, coût) en 3–5 puces.
## Options
- Option A — (1–2 lignes : idée + implications)
- Option B — (1–2 lignes)
- Option C — (facultatif)
## Décision
- Option retenue + raisons (critères utilisés).
## Conséquences
+ Effets positifs (mesurables si possible)
– Effets négatifs / risques / dettes
## Impact & Contrat
- API/DB/Events/Dépendances : ce qui change (breaking ? non ?)
- Tests attendus (noms de cas, invariants, erreurs)
- Rollout/migration (feature flag, rétro-compat, fenêtre de dépréciation)
## Suivi
- Actions pour passer à "accepted" (tâches/PR)
- Revue à la date : YYYY-MM-DD (si besoin)En vrai, il y a plein de façons d’écrire un ADR. Mais si vous en avez jamais vu, on peut commencer par ça.
Les statuts c’est important
Le premier point c’est le cycle de vie. Les ADRs ont tendance à s’empiler. On les ajoute sur la pile et ensuite on les oublie. Sauf que quand on les lit a posteriori, c’est un peu pénible d’en trouver un qui remplace complètement ce qui a été dit dans le précédent. On ne sait pas quand cette liste chaînée finit. Donc pensez à les déprécier, à les taguer en “superseded” pour indiquer qu’ils ont été remplacés. Et ajoutez une référence vers le nouveau.
Statuts (définitions rapides) :
- proposed : décision envisagée
- accepted : décision actée et en vigueur
- superseded : remplacée par un autre ADR
- deprecated : obsolète (mais pas forcément remplacée)
Bonne pratique : créez /docs/adr/index.md et listez les ADR d’actualité. Ça facilite aussi la découverte pour un agent ou un serveur MCP [lien interne].
Bon quand je code tout seul c’est évident que mes ADRs passent en accepted par défaut.
Quand écrire un ADR ?
Il y a plein de bonnes raisons d’écrire un ADR :
- Changement de contrat public (API, schéma, events).
- Impacts perf, sécurité, coût, ou dépendance clé.
- Choix non réversibles à court terme.
- Éviter une discussion fantôme (machine à café, Slack) qui ne survivra pas jusqu’à la PR.
Mais de manière générale, à l’intuition, ça fonctionne.
La charge mentale, c’est un signal. Quand je réalise que je garde une connaissance pour moi, je l’écris dans un ADR.
Je veux aussi pouvoir changer d’avis facilement. C’est compliqué de remettre en question une décision si on a pas le contexte dans lequel elle a été prise. Mon moi du futur va pouvoir adapter les décisions plus facilement s’il peut voir ce qui a changé dans le contexte.
Quelles étaient les options ?
J’aime bien les options. Parce qu’une des premières questions que j’ai en arrivant sur le code, c’est : “Pourquoi ils n’ont pas fait comme ça plutôt ?”. Et comme je pense que je suis plus intelligent, je réécris tout le code… pour arriver à une impasse qu’ils avaient anticipée. Oui, parce qu’ils étaient intelligents, les gens du passé, en fait.
On met quoi dans la Definition Of Done ?
Phénomène fascinant : j’ai longtemps bossé sur des projets où la Definition of Done n’était… pas écrite. Et ça ne me choquait pas. Le consensus me semblait plus important que la formalisation.
En français : je préfère qu’on fasse tous la même chose. Plutôt que d’avoir un beau document tiré à quatre épingles qu’on oublie dans Confluence.
Si on documente dans le code, la DoD devrait figurer dans le README.md. À portée de tous.
Chaque projet aura des critères différents :
- Sur une app mobile : la feature est utilisable en mode avion.
- Sur une app web : les images sont compressées.
- Sur une infra : testé en environnement iso-prod (oui, ça surprend).
- Tous les warnings du linter sont résolus (ou pas).
- La fonctionnalité n’aura pas besoin d’être refactorisée au sprint suivant.
- La documentation technique est à jour.
- Accessibilité : est-ce que les boutons font tous au moins 21dp (Android)
Chaque contributeur est responsable de respecter la DoD.
Dans l’imaginaire Agile, on coche la DoD en Sprint Review, PO et équipe réunis autour d’un ticket. En réalité, chaque dev est responsable de la DoD de sa feature. Et s’il ne l’applique pas… on convoque le conseil de discipline : Lead Dev, PO, Tech Lead. Denis Brogniart en maître du feu. Leur décision est irrévocable. 🔥
Ce qu’il ne faut jamais faire ? Ajouter des validateurs en cascade :
- Le DA a validé la charte.
- Le PO a validé l’US.
- Le QA a fait la recette.
- Le dev back a confirmé que le dev front a bien intégré.
- Le dev front a confirmé que l’API respecte le blueprint.
Bref : ça s’empile, ça s’enchaîne… et ça devient kafkaïen.
Qu’est-ce qui se passe quand la Definition Of Done est floue ?
Je me rappelle ma première appli mobile. Un jour, le N+2 passe derrière mon épaule, prend mon iPhone de dev… et coupe le wifi. Crash direct.
Le dev sénior à côté me glisse : « Ah, il fait ça à chaque fois. »
Autre souvenir : j’ajoute un bouton sur une vue faite par un autre dev. À chaque clic, ma vue se ferme. Bizarre.
En réalité, il n’avait pas implémenté le bouton back. Il avait collé un “retour arrière” sur toute la vue, en se disant qu’il coderait le vrai bouton plus tard. Et ça, c’était une convention tacite dans l’équipe. J’aurais dû le savoir.
À quoi ça ressemble une DoD ?
Et bien parfois ça tient en un paragraphe, une bullet-list. Il faut que ce soit clair. Si c’est trop long, personne ne le vérifiera. Dans l’idéal on peut même l’implémenter dans la CI/CD.
## Definition of Done (DoD)
- [ ] Code compilé, tous les tests passent en CI.
- [ ] Aucun warning bloquant (linter, type-checker).
- [ ] Documentation mise à jour (README / ADR / Changelog).
- [ ] Accessibilité vérifiée (ex. boutons > 21dp, labels ARIA).
- [ ] Mode déconnecté testé (mobile).
- [ ] Perf OK : temps de réponse < 200ms sur endpoint critique.
- [ ] Pas de TODO/FIXME laissés en production.Voilà c’est tout !
Pas plus pas moins. On pourrait imaginer que ce soit un bloc qu’on copie sur chaque PR.
On veut de la concision. Contrairement à un article fleuve que je pourrais écrire.
Et on a plein d’outils Docs as code facilement
Quand j’ai demandé à Julia March-Navarro quel était le breakpoint pour avoir un spécialiste pour la doc, elle m’a répondu :
“dès qu’il y a des utilisateurs payants.
Peu de moyens ? Un·e freelance ponctuel·le suffit.
Sinon : se former + outils d’assistance (vale.sh, etc.).”
Et ça m’a poussé à creuser les outils. Parce que oui, Vale CLI [Vale — Documentation officielle](https://vale.sh/docs/) est devenu une nouvelle tendance. Le monde “docs as code” avait d’abord commencé par le fait de sortir la documentation développeur du confluence pour la mettre sur Git avec un générateur de site statique comme Jekyll ou Hugo. On a ensuite eu le droit à une série de CMS comme Docusaurus ou MKDocs. Mais aujourd’hui le “new kids on the blocks” c’est Vale CLI ou “vale.sh”.
Passer au next le Vale.sh
L’outil fonctionne en CLI et devient un linter de documentation technique. Parce que tout le monde utilise des outils différents pour écrire. Certains utilisent Grammarly, d’autres LanguageTool. Moi j’aime bien utiliser le score Hemingway (même si sur le style je suis plutôt Bukowski), d’autres préfèreront Flesch.
Mais à la fin, tout le monde va utiliser le linter tel qu’il est spécifié dans Vale.sh
C’est du YAML donc par exemple, si je veux détecter la voix passive :
# .vale/styles/Readability/PassiveVoiceFR.yml
extends: existence
message: "Voix passive détectée : '{{match}}'. Préfère l’actif."
level: warning
scope: sentence
tokens:
# Auxiliaire être + participe passé basique
- '\b(suis|es|est|sommes|êtes|sont|étais|était|étions|étaient|été|sera|seront)\b\s+\w+(é|i|u|és|is|us|ée|ie|ue|ées|ies|ues)\b'Bon va pas tout écrire, il y a déjà des supers package tout prêts : “write-good”, “alex”. Ce sont des standards de l’industrie qui sont facile à prendre en main. Et les warning seront explicites.
monfichier.md:5:12:Google.Acronyms:warning: Définissez les acronymes lors de leur première occurrence : 'SLO', 'SLA'.
monfichier.md:14:1:Google.Please:warning: Évitez "s’il vous plaît" : soyez direct dans vos instructions.
monfichier.md:22:5:Google.Links:warning: Évitez "cliquez ici". Intégrez le lien dans une phrase descriptive.Et ça s’intègre dans la CI/CD
Github Action peut très bien charger Vale et le lancer sur chaque PR.
name: Vale Lint
on: [pull_request]
jobs:
vale:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Vale
run: |
curl -fsSL https://install.goreleaser.com/github.com/errata-ai/vale.sh.sh | sh
sudo mv ./bin/vale /usr/local/bin/vale
- name: Run Vale
run: |
vale .Ça fonctionne encore plus facilement sur GitLab CI ou d’autres outils. C’est normal pour une CLI.
Et on passe d’un assistant à un “Gate”. Un critère d’acceptation avant d’aller en production.
Vous aurez peut-être besoin d’un git diff pour forcer la mise à jour de la documentation développeur, par exemple.
if ! git diff --name-only origin/main...HEAD | grep -E 'docs/|README.md|CHANGELOG.md'; then
echo "❌ Aucune mise à jour de documentation détectée."
exit 1
fi
Front matter pour améliorer la maintenance et la découverte
C’est un peu le dernier outil qui est simple mais indispensable à mon sens. Si vous n’avez jamais vu de “front matter”, c’est un en-tête de fichier markdown.
Le format a une spécification ouverte est peut-être supporté par votre générateur de site statique ou votre CMS de Doc : Hugo, Jekyll, MkDocs, Docusaurus
---
title: Politique d’erreurs API
description: Codes d’erreur, messages et exemples de gestion côté client.
owner: @julia
status: active
review_after: 2026-03-01
canonical_url: https://acme.dev/docs/api/errors
tags: [api, errors, client]
---
Et ça permet une petite automatisation au passage :
Et vous pouvez bien sûr faire un script pour vérifier que la doc est toujours à jour, en utilisant le tag “review_after”. Exemple en python. Vous pouvez le lancer dans votre CI.
# .github/scripts/check_frontmatter.py
import re, sys, os, datetime, yaml
ERR=0
fm_re = re.compile(r"^---\n(.*?)\n---", re.S)
for root,_,files in os.walk("docs"):
for f in files:
if not f.endswith(".md"): continue
p=os.path.join(root,f)
s=open(p,encoding="utf-8").read()
m=fm_re.match(s)
if not m:
print(f"❌ {p}: front-matter manquant"); ERR=1; continue
data=yaml.safe_load(m.group(1)) or {}
for k in ["owner","review_after","title"]:
if not data.get(k):
print(f"❌ {p}: champ requis manquant: {k}"); ERR=1
if data.get("review_after"):
try:
d=datetime.date.fromisoformat(str(data["review_after"]))
if d < datetime.date.today():
print(f"❌ {p}: review_after dépassé ({d})"); ERR=1
except Exception:
print(f"❌ {p}: review_after non ISO (YYYY-MM-DD)"); ERR=1
sys.exit(ERR)
Est-ce qu’il faut le préciser dans la DoD ?
Non ! Par contre si on active ça sur la CI sans en parler avant, on sera bien sûr ce moment où la DoD a bougé et ça a laissé la moitié des gens de côté 😄
Le frontmatter a bien un intérêt supplémentaire : rendre la documentation technique plus facile à ingérer pour les LLMs et IA. On en parle un peu ?
Des guides utiles aux devs et aux IA
Les guides dont vous avez besoin dépendent du projet… et des parties prenantes.
Dans l’immédiat, l’objectif est de réduire la charge mentale du ou des développeurs.
Mais dès demain, il faudra aussi penser à l’onboarding de votre futur collègue, ou de votre remplaçant (parce que vous avez eu une promotion, bien sûr).
Votre README.md devient alors un guide pour les autres — mais aussi pour vous.
Il vous aide à reprendre ce projet après un changement de machine, ou tout simplement au retour de vacances.
Par ailleurs, votre projet accueillera peut-être des contributeurs externes.
Dans le cadre d’un inner source limité, par exemple, vous aurez besoin d’un guide de contribution : le fameux CONTRIBUTING.md.
Enfin, la nature même du projet compte : web, hardware, mobile, front ou back… chaque contexte appelle ses propres supports.
Quelle est la différence entre documentation développeur et documentation utilisateur ?
J’ai posé la question à Jean-Philippe Encausse :
« Dans le cas des acteurs hardware [ESP32], ils ne font pas la doc parce qu’ils pensent hardware.
C’est même dingue : ce qui sort d’usine ne marche parfois pas, ou juste sur un hello-world.
C’est pour ça que mon choix de hard se fonde uniquement sur deux critères :
– un repo Git avec un use-case fonctionnel ;
– un dev qui répond aux issues. »
Sur mes applications web, j’ai pris une autre habitude.
Je laisse systématiquement de la documentation API et sécurité à destination d’un auditeur : un pentesteur.
Son objectif est clair : cartographier toutes les fonctionnalités.
Ensuite, il vérifie l’OWASP Top 10 sur chaque feature, au minimum.
C’est pourquoi mon guide explicite chaque fonctionnalité et précise comment j’ai testé l’OWASP Top 10 dessus.
Pour autant, il faut rester sobre.
Trop de créativité, et on se retrouve avec un buisson de guides… pas tous à jour.
Les guides demandent beaucoup d’efforts de mise à jour
C’est un des premiers sujets à aborder.
Il faut le dire : écrire un guide, c’est difficile — pour plusieurs raisons.
D’abord, il faut être créatif dans les cas d’usage.
C’est d’ailleurs l’un des premiers critères d’une doc négligée, d’après Julia : « peu d’alternatives ou de cas d’usage envisagés. »
Mais surtout, de mauvais guides peuvent mettre les LLMs — ou autres agents IA — dans le décor.
Jean-Philippe partage une expérience parlante :
« Sur des niches comme Arduino, les agents sont nullissimes. Ils se basent sur du code 2023.
Même si tu leur dis d’aller chercher en ligne, ils mélangent tout, et on perd un temps fou.
Est-ce qu’une vraie doc changerait la donne ? Je ne pense pas.
Il leur faut surtout des exemples de code pour apprendre.
J’ai eu un cas de ouf : un UUID style “012012012…3”.
Le LLM refusait que ça se termine par 3. Il mettait 2, parce que, dans son “inconscient”, c’était 2 le standard.
Je lui répétais que c’était 3 ; il disait “oui oui”… puis remettait 2 ! »
Et c’est vrai : ces guides nécessitent rapidement une équipe à plein temps pour les maintenir.
Mais bien tenus à jour, ils deviennent de puissants multiplicateurs de temps.
Ils évitent les tickets redondants, les questions Slack, les onboarding douloureux.
Et surtout, ils évitent que les IA racontent n’importe quoi.
Chez Strapi, Pierre Wizla le constate aussi :
« Quelques tech writers couvrent 5 ou 6 squads. Impossible d’être à tous les rituels Scrum. »
Alors, beaucoup d’équipes finissent par organiser des mini-sprints ou des journées de refonte.
On anime des ateliers, on vérifie que les guides sont fonctionnels, et on les met à jour.
Vers MCP est au-delà
Nos trois experts sont unanimes : il faut utiliser l’IA pour générer de la documentation technique.
Après tout, on ne peut pas être ingénieur logiciel et expert en rédaction.
Ce sont deux métiers à part entière — et une seule journée ne suffit pas pour les cumuler.
Même lorsqu’on est rédacteur, l’IA reste utile.
Elle permet de gagner du temps sur l’ingestion des informations.
Pierre Wizla partage son usage : « Je peux faire avaler des diffs de PR, un RFC et mes notes à Claude ou Gemini pour une vue d’ensemble. »
Mais surtout, l’IA devient un moyen d’interagir avec la documentation développeur.
Si les exemples de code sont le strict minimum pour que les agents puissent guider les utilisateurs, on peut aller encore plus loin.
“Chez Strapi :
Chatbot Kapa entraîné sur toute la doc (Ask AI sur https://docs.strapi.io).
Fichiers LLMs.txt et LLMs-full.txt pour que les modèles ingèrent la doc.
Bouton pour copier le Markdown brut et l’injecter dans un LLM.”
Et demain on parle d’un serveur MCP pour que la Doc soit directement dans l’IDE ou même d’une intégration sur le CMS, les snippets de code pourront être prompter pour s’adapter à l’utilisateur. Cela nécessite de RAGifier tout le contenu.
Bref : la documentation technique ne sera plus seulement un PDF oublié ou un site statique. Elle sera un agent dans ton IDE, un copilote qui connaît ton projet. Et ça, ça change tout.
Conclusion : la documentation technique, c’est comme les chocapics. C’est avant et pas après le lait.
Tu as tout : un cycle DocDD (ADR → contrat & tests → doc avant push), une DoD atomique dans le README, et des garde-fous outillés (Vale en CI, script “doc modifiée ?”, front-matter pour l’ownership et la fraîcheur).
Les guides ne sont plus un luxe : ils servent aux humains et, de plus en plus, aux IA (LLMs.txt, ingestion, demain MCP dans l’IDE). C’est ça, le vrai changement : la documentation technique devient une interface — entre devs, et entre nos outils.
Si tu ne devais faire qu’un seul pas dès maintenant :
mets la DoD dans le README et casse la CI si la doc n’est pas mise à jour. Le reste suivra.
À emporter (ultra-court)
-
Doc = contrat avant le code, artefact qui l’accompagne.
-
DoD claire, sans validateurs en cascade.
-
ADR d’une page, statuts gérés (superseded).
-
Vale + CI pour standardiser la prose et bloquer les PR orphelines.
-
Front-matter (owner, review_after, status) pour la maintenance et les agents.
-
Guides tournés vers les parties prenantes… et les IA.
Dernier mot
Ce que je vous propose aujourd’hui, c’est pas une usine à documentation. Ce sont des petites habitudes qui appliquée au quotidien vont réduire la charge mental de chacun. Et au long terme ça fera la différence.
Je vous ai parlé du CLAUDE.md ? Je vous partage mon prompt sur LinkedIn. Retrouvez la vidéo qui fait mention de cet article et participez à la conversation.
