Anti-patterns : les erreurs qui tuent la documentation

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 ?

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

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.

1. La documentation devient obsolète ou introuvable
2. Les utilisateurs arrêtent de la consulter (« c’est jamais à jour »)
3. Les auteurs arrêtent de la maintenir (« personne ne la lit de toute façon »)
4. La documentation devient encore plus obsolète
5. 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

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

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à

C’est rarement intentionnel. L’éparpillement se produit progressivement :

1. L’équipe A utilise Confluence (c’est l’outil officiel)
2. L’équipe B préfère Notion (plus moderne)
3. Les devs mettent les trucs techniques dans les README
4. Quelqu’un crée un Google Doc pour une procédure urgente « en attendant »
5. Le « en attendant » dure 3 ans

La solution

Une URL centrale unique pour toute la documentation technique.

✅ Bonne pratique

docs.entreprise.com/
├── services/
│   └── payments/           ← Tout sur Payments est ICI
├── runbooks/
└── architecture/

Une seule réponse possible : « docs.entreprise.com/services/payments »

❌ Anti-pattern

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

Le test de l'URL unique

Si quelqu’un vous demande « où est la doc ? », vous devez pouvoir répondre par une URL. Pas « cherche dans le wiki » ou « demande à Jean-Pierre ». Si votre réponse contient « cherche » ou « demande », vous avez un problème.

Comment s’en sortir

Si vous êtes déjà dans cette situation :

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

2. Migrez progressivement

   Commencez par les documents critiques (runbooks, procédures incident). Le reste peut attendre ou mourir dans l’ancien système.

3. Mettez les anciennes sources en lecture seule

   Ajoutez un bandeau : « Cette doc a migré vers [URL]. Cette page n’est plus maintenue. »

4. Redirigez si possible

   Configurez des redirections automatiques des anciennes URLs.

---

Anti-pattern #2 : La documentation « write-only »

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

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

Tester avec un utilisateur réel avant de considérer la doc comme terminée.

Le test idéal :

1. Trouvez un cobaye

   Quelqu’un qui ne connaît pas (ou peu) le sujet. Idéalement, quelqu’un qui ressemble à votre utilisateur cible.

2. Observez sans intervenir

   Laissez la personne suivre la documentation. Ne répondez pas aux questions, ne corrigez pas les erreurs. Notez où elle bloque.

3. Collectez le feedback

   À la fin : « Qu’est-ce qui n’était pas clair ? Où as-tu hésité ? »

4. Corrigez et re-testez

   Modifiez la doc. Si les changements sont importants, refaites un test.

5. Seulement maintenant : publiez

   La doc est « done » quand quelqu’un l’a suivie avec succès.

Le test du stagiaire

Un classique : faites suivre votre procédure par un stagiaire ou un nouveau. S’ils y arrivent sans aide, votre doc est bonne. S’ils bloquent, vous avez identifié les points à améliorer.

---

Anti-pattern #3 : Pas d’ownership

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

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

Chaque document a UN owner explicite, écrit dans le document lui-même.

---
title: "Runbook : Redémarrage API Payments"
owner: "@alice"              # Responsable principal
backup_owner: "@bob"         # Si Alice est absente ou quitte l'équipe
team: "#payments-oncall"     # Équipe de rattachement
last_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é :

Ownership et Definition of Done Comment définir et maintenir l'ownership de vos documents

---

Anti-pattern #4 : Trop de documentation

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

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à

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

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

La documentation préventive

« On pourrait en avoir besoin un jour » n’est pas une bonne raison de créer un document. Créez la documentation quand le besoin existe réellement, pas « au cas où ».

Priorisez ce qui compte vraiment :

1. Runbooks : utilisés en incident, doivent être parfaits
2. Service Overviews : consultés à chaque onboarding et investigation
3. Procédures fréquentes : ce que les gens font régulièrement
4. 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 »

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

• 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

Aller à l’essentiel. Un runbook tient sur une page. Un Service Overview sur deux pages maximum.

❌ Le roman

# 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 startup
dans 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ète
dans l'espace Confluence « Legacy » si vous avez les droits
d'accès, sinon demandez à Marie du département IT), nous avons
dé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-payments

L’utilisateur qui a besoin de redémarrer en urgence doit scroller 47 pages. Il ne le fera pas.

✅ L'essentiel

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

Le test du scroll

Si l’utilisateur doit scroller pour trouver l’information dont il a besoin en situation d’urgence, votre document est trop long. Mettez l’essentiel en haut, les détails en bas (ou dans un autre document).

---

Anti-pattern #6 : La documentation sans contexte

Le symptôme

# Configuration
server.port=8080
server.timeout=30
db.pool.size=20

C’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

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

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 sont
optimisé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

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

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

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

La période de transition

Pendant une migration, vous aurez temporairement deux sources. C’est normal et inévitable. Mais fixez une deadline claire (3-6 mois max) et communiquez que l’ancienne source est dépréciée.

---

Anti-pattern #8 : Les reviews de façade

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

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

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.

Le reviewer naïf

La meilleure review vient de quelqu’un qui ne connaît pas le sujet. S’il comprend la doc, vos utilisateurs aussi. S’il a des questions, vos utilisateurs en auront aussi.

---

Anti-pattern #9 : La documentation « à faire plus tard »

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

« 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

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écessaire

Ownership et Definition of Done Comment intégrer la documentation dans votre DoD

---

Anti-pattern #10 : Ignorer le feedback utilisateur

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

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

Canal de feedback + suivi systématique.

1. Canal visible : bouton « Signaler un problème » sur chaque page
2. Triage régulier : quelqu’un lit les retours chaque semaine
3. Action ou explication : soit on corrige, soit on explique pourquoi non
4. Remerciement : « Merci @alice, c’est corrigé » — ça encourage

---

Anti-pattern #11 : Pas de recherche fonctionnelle

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

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

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

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

• 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

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.

Reviews et fraîcheur Comment organiser les cycles de review et d'archivage

---

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.

1 URL unique pour toute la doc technique ? Oui Non

2 Chaque document a un owner identifié ? Oui Non

3 Documentation testée avant publication ? Oui Non

4 Processus de review fonctionnel ? Oui Non

5 Recherche full-text efficace ? Oui Non

6 Documents obsolètes archivés ? Oui Non

7 Doc intégrée dans la Definition of Done ? Oui Non

8 Feedback utilisateur possible ? Oui Non

9 Source unique (pas wiki + Git) ? Oui Non

10 Reviews substantives ? Oui Non

0/10 répondu Voir le diagnostic

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

Ressources complémentaires

Ownership et Definition of Done Définir clairement qui maintient quoi

Reviews et fraîcheur Organiser les cycles de review et d'archivage

Documentation as Code L'approche Git + Markdown pour éviter les anti-patterns

Service Overview Créer une documentation essentielle et efficace