Vous avez investi du temps et de l’énergie pour créer de la documentation. L’équipe l’utilise au début, tout le monde est content. Six mois plus tard, plus personne ne la consulte. Elle est devenue un cimetière de fichiers que tout le monde évite.
Que s’est-il passé ?
Probablement un ou plusieurs anti-patterns — ces erreurs qui semblent anodines au départ mais qui, accumulées, rendent la documentation inutile voire dangereuse.
Pourquoi parler d’anti-patterns ?
Section intitulée « Pourquoi parler d’anti-patterns ? »Un anti-pattern est une solution qui paraît bonne sur le moment mais qui crée plus de problèmes qu’elle n’en résout. En développement logiciel, on connaît bien le concept : le « God Object », le « Spaghetti Code », le « Copy-Paste Programming ». La documentation a ses propres anti-patterns, tout aussi destructeurs.
Le problème avec les anti-patterns documentaires, c’est qu’ils sont insidieux. Leurs effets négatifs n’apparaissent pas immédiatement. Vous créez une page dans un wiki, puis une autre dans Confluence, puis un README dans un repo… Et un jour, personne ne sait plus où trouver quoi.
Ce guide liste les erreurs les plus fréquentes et explique comment les éviter — ou comment en sortir si vous y êtes déjà.
Le cycle vicieux de la mauvaise documentation
Section intitulée « Le cycle vicieux de la mauvaise documentation »Avant d’entrer dans les détails, comprenons pourquoi la documentation se dégrade. Ce n’est pas une fatalité, c’est un cercle vicieux qu’il est possible de briser.
- La documentation devient obsolète ou introuvable
- Les utilisateurs arrêtent de la consulter (« c’est jamais à jour »)
- Les auteurs arrêtent de la maintenir (« personne ne la lit de toute façon »)
- La documentation devient encore plus obsolète
- Retour à l’étape 1, en pire
La bonne nouvelle : chaque anti-pattern que vous corrigez brise une partie du cycle. Vous n’avez pas besoin de tout résoudre d’un coup. Commencez par les problèmes les plus visibles.
Anti-pattern #1 : La documentation éparpillée
Section intitulée « Anti-pattern #1 : La documentation éparpillée »Le symptôme
Section intitulée « Le symptôme »Quelqu’un pose une question simple : « C’est où la doc du service Payments ? »
Les réponses fusent :
- « Dans le wiki interne »
- « Non, on l’a migrée sur Confluence »
- « Attends, y’a aussi un Google Doc que Jean-Pierre avait partagé »
- « Le README du repo est pas mal aussi »
- « Ah et y’a le Notion de l’équipe Billing »
Cinq sources. Cinq versions potentiellement différentes. Laquelle est la bonne ?
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »La documentation éparpillée est peut-être l’anti-pattern le plus destructeur, pour plusieurs raisons :
| Conséquence | Impact |
|---|---|
| Introuvable = inutilisée | Si je dois chercher 10 minutes, j’abandonne |
| Doublons contradictoires | Quelle version croire ? Souvent la mauvaise |
| Maintenance impossible | Mettre à jour 5 sources ? Personne ne le fait |
| Onboarding cauchemardesque | Les nouveaux doivent apprendre 5 outils |
Comment on en arrive là
Section intitulée « Comment on en arrive là »C’est rarement intentionnel. L’éparpillement se produit progressivement :
- L’équipe A utilise Confluence (c’est l’outil officiel)
- L’équipe B préfère Notion (plus moderne)
- Les devs mettent les trucs techniques dans les README
- Quelqu’un crée un Google Doc pour une procédure urgente « en attendant »
- Le « en attendant » dure 3 ans
La solution
Section intitulée « La solution »Une URL centrale unique pour toute la documentation technique.
docs.entreprise.com/├── services/│ └── payments/ ← Tout sur Payments est ICI├── runbooks/└── architecture/Une seule réponse possible : « docs.entreprise.com/services/payments »
- Wiki interne page 47- Confluence > Espaces > Tech > Legacy > Archive > API- Google Drive > Shared > Technique > API > v2 > doc finale v3 FINAL.docx- README.md (mais dans quel repo ?)- Notion équipe Billing (invitation requise)Cinq minutes de recherche, résultat incertain.
Comment s’en sortir
Section intitulée « Comment s’en sortir »Si vous êtes déjà dans cette situation :
-
Choisissez LA source de vérité
Décidez quel outil sera l’unique référence. Peu importe lequel, tant que c’est UN seul.
-
Migrez progressivement
Commencez par les documents critiques (runbooks, procédures incident). Le reste peut attendre ou mourir dans l’ancien système.
-
Mettez les anciennes sources en lecture seule
Ajoutez un bandeau : « Cette doc a migré vers [URL]. Cette page n’est plus maintenue. »
-
Redirigez si possible
Configurez des redirections automatiques des anciennes URLs.
Anti-pattern #2 : La documentation « write-only »
Section intitulée « Anti-pattern #2 : La documentation « write-only » »Le symptôme
Section intitulée « Le symptôme »L’auteur écrit consciencieusement une procédure de 30 étapes. Il la publie. Mission accomplie !
Six mois plus tard, quelqu’un essaie de la suivre en situation d’urgence. Ça ne marche pas. L’étape 7 fait référence à un serveur qui n’existe plus. L’étape 15 utilise une commande dépréciée. L’étape 23 suppose des permissions que personne n’a.
La doc n’a jamais été testée avec un vrai utilisateur.
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »Une documentation non testée est une bombe à retardement. Elle donne une fausse confiance : on pense avoir documenté, alors qu’on a juste écrit.
| Situation | Documentation testée | Documentation « write-only » |
|---|---|---|
| Incident à 3h du mat | L’opérateur suit la procédure, résout en 15 min | L’opérateur découvre que ça ne marche pas, panique, 2h de galère |
| Onboarding | Le nouveau suit le guide, autonome en 2 jours | Le nouveau bloque, dérange tout le monde, frustration |
| Audit | Procédures documentées ET fonctionnelles | « On a de la doc » mais elle ne reflète pas la réalité |
La solution
Section intitulée « La solution »Tester avec un utilisateur réel avant de considérer la doc comme terminée.
Le test idéal :
-
Trouvez un cobaye
Quelqu’un qui ne connaît pas (ou peu) le sujet. Idéalement, quelqu’un qui ressemble à votre utilisateur cible.
-
Observez sans intervenir
Laissez la personne suivre la documentation. Ne répondez pas aux questions, ne corrigez pas les erreurs. Notez où elle bloque.
-
Collectez le feedback
À la fin : « Qu’est-ce qui n’était pas clair ? Où as-tu hésité ? »
-
Corrigez et re-testez
Modifiez la doc. Si les changements sont importants, refaites un test.
-
Seulement maintenant : publiez
La doc est « done » quand quelqu’un l’a suivie avec succès.
Anti-pattern #3 : Pas d’ownership
Section intitulée « Anti-pattern #3 : Pas d’ownership »Le symptôme
Section intitulée « Le symptôme »« Qui maintient cette doc ? »
- « Je sais pas »
- « C’était Jean-Pierre mais il est parti il y a 6 mois »
- « L’équipe Infra… ou Dev… je suis pas sûr »
- « Personne officiellement »
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »Un document sans responsable est un document abandonné. Personne ne le met à jour quand le système change. Personne ne répond aux questions. Personne ne le supprime quand il devient inutile.
C’est le chemin direct vers la documentation zombie : elle existe, elle encombre, mais elle n’est plus vivante.
La solution
Section intitulée « La solution »Chaque document a UN owner explicite, écrit dans le document lui-même.
---title: "Runbook : Redémarrage API Payments"owner: "@alice" # Responsable principalbackup_owner: "@bob" # Si Alice est absente ou quitte l'équipeteam: "#payments-oncall" # Équipe de rattachementlast_reviewed: 2025-01-15 # Dernière vérification---L’ownership ne signifie pas que l’owner fait tout seul. Ça signifie que :
- Il y a une personne à contacter si question
- Il y a une personne responsable de la mise à jour
- Il y a une personne qui décide si archiver ou pas
Pour aller plus loin sur ce sujet, consultez le guide dédié :
Anti-pattern #4 : Trop de documentation
Section intitulée « Anti-pattern #4 : Trop de documentation »Le symptôme
Section intitulée « Le symptôme »« Tout est documenté chez nous ! On a 500 pages de doc ! »
Mais quand vous cherchez une information précise, vous ne trouvez rien. Ou vous trouvez 12 pages qui parlent vaguement du sujet sans répondre à votre question.
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »Trop de documentation est parfois pire que pas assez :
| Problème | Conséquence |
|---|---|
| Paralysie par l’information | Face à 500 pages, on abandonne |
| Coût de maintenance explosif | Chaque page doit être maintenue |
| Fausse sécurité | « On a documenté » mais personne ne trouve |
| Bruit qui masque le signal | L’info critique est noyée |
Comment on en arrive là
Section intitulée « Comment on en arrive là »Souvent par excès de zèle ou par obligation formelle :
- « Documentons tout au cas où »
- « L’audit demande de la documentation »
- « Chaque feature doit avoir sa page »
Le résultat : des centaines de pages que personne ne lit.
La solution
Section intitulée « La solution »Appliquez la règle du 80/20 : 20% des documents couvrent 80% des besoins.
Avant de créer un document, posez-vous ces questions :
| Question | Si la réponse est floue… |
|---|---|
| Qui va lire ce document ? | Peut-être personne |
| Quand va-t-il le lire ? | Peut-être jamais |
| Combien de fois par mois ? | Si < 1, vraiment nécessaire ? |
| Que se passe-t-il sans ce doc ? | Si « rien de grave », ne le créez pas |
Priorisez ce qui compte vraiment :
- Runbooks : utilisés en incident, doivent être parfaits
- Service Overviews : consultés à chaque onboarding et investigation
- Procédures fréquentes : ce que les gens font régulièrement
- FAQ : les questions qu’on vous pose tout le temps
Le reste peut probablement attendre — ou ne jamais exister.
Anti-pattern #5 : La documentation « roman »
Section intitulée « Anti-pattern #5 : La documentation « roman » »Le symptôme
Section intitulée « Le symptôme »Un document de 50 pages pour expliquer comment redémarrer un service. L’historique complet du projet depuis 2015. La justification philosophique de chaque choix technique. Des parenthèses dans les parenthèses.
L’auteur est fier : « C’est exhaustif ! »
Personne ne lit au-delà de la page 3.
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »- Personne ne lit : trop long, trop dense
- L’information critique est noyée : la commande de redémarrage est page 47
- Impossible à maintenir : 50 pages à mettre à jour à chaque changement
- Temps perdu : l’auteur a passé des heures pour un résultat inutile
La solution
Section intitulée « La solution »Aller à l’essentiel. Un runbook tient sur une page. Un Service Overview sur deux pages maximum.
# Service API Payments
## Historique et contexte
Ce service a été créé en 2019 par l'équipe de Jean-Pierre(qui a depuis quitté l'entreprise pour rejoindre une startupdans la blockchain, mais c'est une autre histoire). À l'origine,il utilisait une architecture monolithique basée sur Java 8,mais en 2021, lors de la grande migration vers les microservices(projet Phoenix, dont vous trouverez la documentation complètedans l'espace Confluence « Legacy » si vous avez les droitsd'accès, sinon demandez à Marie du département IT), nous avonsdécidé de réécrire le service en Go parce que...
[47 pages plus tard]
## Comment redémarrer le service
Si vous êtes arrivé jusqu'ici, félicitations. Voici la commande :
systemctl restart api-paymentsL’utilisateur qui a besoin de redémarrer en urgence doit scroller 47 pages. Il ne le fera pas.
# Service API Payments
**Owner** : @alice | **Équipe** : #billing | **Criticité** : Haute
## En bref
Traite les paiements CB. ~500K transactions/jour.Downtime = perte de revenus immédiate.
## Redémarrage
systemctl restart api-payments
Vérification : curl localhost:8080/health → 200 OK
## Architecture
[Diagramme de 5 éléments max]
## Contacts urgents
Oncall : #payments-oncall | Escalade : @bob (manager)Tout tient sur un écran. L’info critique est immédiatement visible.
Anti-pattern #6 : La documentation sans contexte
Section intitulée « Anti-pattern #6 : La documentation sans contexte »Le symptôme
Section intitulée « Le symptôme »# Configurationserver.port=8080server.timeout=30db.pool.size=20C’est quoi ce service ? Pourquoi ces valeurs ? Que se passe-t-il si je les change ? Est-ce que 30, c’est des secondes ou des millisecondes ?
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »La documentation technique sans contexte est inutilisable pour quiconque n’est pas déjà expert du sujet. Et si vous êtes déjà expert, vous n’avez probablement pas besoin de la doc.
Les problèmes :
- Impossible de comprendre sans connaissance préalable
- Impossible de savoir si on peut modifier sans risque
- Impossible de debugger (« pourquoi cette valeur ? »)
La solution
Section intitulée « La solution »Contexte avant détails : expliquer le « pourquoi » avant le « quoi ».
# Configuration API Payments
Ce service traite les paiements CB. Il communique avec l'API Stripe(timeout configuré à 25s côté Stripe). Les paramètres ci-dessous sontoptimisés pour notre charge actuelle (~500K transactions/jour).
| Paramètre | Valeur | Pourquoi cette valeur | Si je change ? ||-----------|--------|----------------------|----------------|| `server.port` | 8080 | Port standard interne | Mettre à jour le load balancer || `server.timeout` | 30s | Stripe timeout = 25s, +5s marge | < 25s = erreurs timeout || `db.pool.size` | 20 | 10 conn/pod × 2 pods | Voir capacity planning doc |Le lecteur comprend maintenant :
- À quoi sert ce service
- Pourquoi chaque valeur a été choisie
- Les conséquences d’une modification
Anti-pattern #7 : Wiki ET Git en parallèle
Section intitulée « Anti-pattern #7 : Wiki ET Git en parallèle »Le symptôme
Section intitulée « Le symptôme »« La doc utilisateur est dans le wiki. La doc technique est dans le repo. Les runbooks sont dans Confluence. Les ADR sont dans le repo aussi, mais pas le même. »
Deux sources de vérité (ou plus) pour le même type d’information.
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »Quand il y a plusieurs sources, personne ne sait laquelle est à jour. Inévitablement :
- Les sources divergent
- Les gens mettent à jour l’une mais pas l’autre
- Les conflits ne sont jamais résolus
- La confiance s’érode (« c’est jamais fiable de toute façon »)
La solution
Section intitulée « La solution »Une seule source de vérité. Point.
Si vous adoptez Docs-as-Code (Git + Markdown), tout va dans Git. Le wiki devient lecture seule avec un bandeau de redirection, puis est fermé.
Si vous gardez le wiki, les README des repos ne contiennent que le strict minimum (lien vers la doc wiki) et pas de documentation dupliquée.
Le pire : maintenir les deux « parce qu’on a toujours fait comme ça ».
Anti-pattern #8 : Les reviews de façade
Section intitulée « Anti-pattern #8 : Les reviews de façade »Le symptôme
Section intitulée « Le symptôme »Le processus dit qu’il faut une review avant publication. Alors quelqu’un approuve la PR en 30 secondes sans lire. « LGTM » (Looks Good To Me).
La doc est publiée. Elle contient une erreur grossière que n’importe quel lecteur attentif aurait vue.
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »Une review de façade est pire que pas de review :
- Elle donne une fausse impression de qualité
- Elle déresponsabilise tout le monde (« quelqu’un a reviewé »)
- Elle détruit la confiance dans le processus
La solution
Section intitulée « La solution »Exiger un commentaire substantif pour chaque review.
Le reviewer doit démontrer qu’il a lu :
- « J’ai testé la procédure, ça fonctionne »
- « Question : pourquoi timeout de 30s et pas 60s ? »
- « Suggestion : ajouter une section sur le rollback »
Un simple « LGTM » ou « ✓ » n’est pas une review.
Anti-pattern #9 : La documentation « à faire plus tard »
Section intitulée « Anti-pattern #9 : La documentation « à faire plus tard » »Le symptôme
Section intitulée « Le symptôme »- « On documentera quand on aura le temps »
- « D’abord on livre la feature, après on documente »
- « J’ai créé un ticket JIRA pour la doc » (ticket jamais traité)
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »« Plus tard » signifie « jamais » dans 90% des cas.
La dette documentaire s’accumule. Au bout de quelques mois, le gouffre est tel que personne n’ose s’y attaquer. La documentation devient un projet à part entière au lieu d’être intégrée au flux normal.
La solution
Section intitulée « La solution »Documentation dans la Definition of Done.
Une feature n’est pas terminée tant que sa documentation n’est pas faite. Ce n’est pas une étape optionnelle qu’on fait « si on a le temps ».
## Definition of Done — Feature
- [ ] Code mergé et déployé- [ ] Tests passent (unit + intégration)- [ ] Monitoring configuré- [ ] **Documentation mise à jour** ← Non négociable- [ ] Runbook créé si nécessaireAnti-pattern #10 : Ignorer le feedback utilisateur
Section intitulée « Anti-pattern #10 : Ignorer le feedback utilisateur »Le symptôme
Section intitulée « Le symptôme »Les utilisateurs signalent des problèmes :
- « Cette procédure ne marche plus »
- « Il manque une étape »
- « Je ne trouve pas l’info X »
Ces retours sont ignorés ou perdus. Personne n’en fait rien.
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »Les utilisateurs sont votre meilleure source d’amélioration. Ils voient les problèmes que vous ne voyez plus (vous êtes trop proche du sujet).
Ignorer leur feedback :
- Perpétue les erreurs
- Décourage les futures contributions
- Renforce l’image de doc inutile
La solution
Section intitulée « La solution »Canal de feedback + suivi systématique.
- Canal visible : bouton « Signaler un problème » sur chaque page
- Triage régulier : quelqu’un lit les retours chaque semaine
- Action ou explication : soit on corrige, soit on explique pourquoi non
- Remerciement : « Merci @alice, c’est corrigé » — ça encourage
Anti-pattern #11 : Pas de recherche fonctionnelle
Section intitulée « Anti-pattern #11 : Pas de recherche fonctionnelle »Le symptôme
Section intitulée « Le symptôme »« Je sais que c’est documenté quelque part… » suivi de 15 minutes de navigation dans des dossiers imbriqués.
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »Sans recherche efficace, même la meilleure documentation est introuvable. L’utilisateur abandonne et retourne à son réflexe : demander à un collègue ou chercher sur Google.
La solution
Section intitulée « La solution »Recherche full-text obligatoire. C’est non négociable.
Critères minimum :
- Recherche sur le contenu (pas juste les titres)
- Résultats instantanés (< 1 seconde)
- Fonctionne sur mobile (incident à 3h du matin)
- Pertinence correcte (le bon résultat en premier)
Les SSG modernes (Astro, Docusaurus, MkDocs) incluent tous une recherche. Si votre outil n’en a pas, changez d’outil.
Anti-pattern #12 : Documentation jamais archivée
Section intitulée « Anti-pattern #12 : Documentation jamais archivée »Le symptôme
Section intitulée « Le symptôme »Des pages qui documentent des services décommissionnés. Des procédures pour des outils qu’on n’utilise plus. Des « TODO » vides depuis 2019.
Pourquoi c’est grave
Section intitulée « Pourquoi c’est grave »- Pollution : difficile de trouver le contenu utile
- Confusion : ce service existe-t-il encore ?
- Faux indicateurs : « On a 500 pages de doc » (dont 300 obsolètes)
La solution
Section intitulée « La solution »Archiver régulièrement — au minimum une fois par an.
docs/├── actifs/ # Documentation vivante│ ├── services/│ └── runbooks/└── archives/ # Documentation morte (mais préservée) ├── 2023/ │ └── service-legacy-decommissione.md └── 2024/Archiver ≠ supprimer. On garde l’historique, mais on le sort du chemin.
Quiz interactif : évaluez votre documentation
Section intitulée « Quiz interactif : évaluez votre documentation »Testez la santé de votre documentation en répondant à ces 10 questions. Le quiz calcule votre score et identifie les points d’amélioration prioritaires.
À retenir
Section intitulée « À retenir »Une source unique
Toute la documentation technique à un seul endroit. Pas de wiki ET Git en parallèle.
Ownership explicite
Chaque document a un responsable nommé. Pas de « c’est l’équipe ».
Tester avant publication
La doc n’est « done » que quand quelqu’un l’a suivie avec succès.
Qualité > Quantité
20% des docs couvrent 80% des besoins. Le reste est du bruit.