Il est 3h du matin. L'alerte PagerDuty, votre outil d'astreinte, vous réveille en sursaut. Le service de paiement est en panne. Votre collègue expert sur ce service ? En vacances au Népal, sans réseau. Vous ouvrez votre portable, cherchez de la documentation... et vous ne trouvez rien. Pas de runbook (la procédure écrite, pas à pas, pour traiter un incident), pas de schéma, pas même un README digne de ce nom.
Les deux prochaines heures seront les plus longues de votre carrière.
Ce scénario n'est pas de la fiction. C'est le quotidien de milliers d'équipes qui ont négligé leur documentation. Et le prix à payer se mesure en heures d'incidents prolongés, en clients perdus, et en burn-out des équipes.
Ce que vous allez apprendre
Section intitulée « Ce que vous allez apprendre »Cette leçon montre, chiffres et cas vécus à l'appui, pourquoi la documentation est une assurance contre les incidents et les départs, puis propose un plan d'action sur 30 jours pour démarrer sans chercher à tout documenter.
- Mesurer le coût d'une documentation absente avec le MTTR (le temps moyen de rétablissement d'un service) et les pertes invisibles.
- Comprendre le bus factor d'une équipe et repérer la connaissance tacite.
- Expliquer le cercle vicieux de la non-documentation et la façon d'en sortir.
- Identifier le minimum vital à documenter : runbooks, checklist, service overview et ADR.
- Installer la documentation comme une pratique continue et lancer un plan sur 30 jours.
Le vrai coût de l'absence de documentation
Section intitulée « Le vrai coût de l'absence de documentation »J'ai vu des équipes brillantes s'effondrer à cause d'un manque de documentation. Pas parce qu'elles ne savaient pas coder, mais parce que le savoir critique était enfermé dans la tête d'une seule personne. Quand cette personne est partie, l'équipe a mis six mois à retrouver son niveau d'efficacité.
Le schéma ci-dessus illustre la différence fondamentale entre deux approches :
- Sans documentation : l'incident déclenche une course contre la montre pour trouver l'expert, attendre sa disponibilité, et comprendre le contexte. Le MTTR (Mean Time To Recover) explose à 4-8 heures.
- Avec documentation : l'incident déclenche la consultation d'un runbook clair. La procédure est suivie, le service est rétabli. MTTR : 20 minutes.
C'est un facteur 10 à 20 de différence. Sur un an, avec des incidents récurrents, cela représente des centaines d'heures économisées.
Les pertes invisibles
Section intitulée « Les pertes invisibles »Au-delà du MTTR, le manque de documentation génère des coûts que personne ne mesure :
Onboarding ralenti
Un nouvel arrivant met 3-6 mois au lieu de 3-6 semaines pour devenir autonome. Pendant ce temps, il pose des questions qui interrompent les autres. Ces interruptions coûtent 23 minutes de reconcentration chacune (étude Microsoft).
Décisions mal informées
Sans ADR (Architecture Decision Records, des fiches qui consignent une décision technique et sa raison), les nouveaux refont les mêmes erreurs de conception que leurs prédécesseurs. Ils ne savent pas pourquoi le système est conçu ainsi, donc ils le cassent en voulant « l'améliorer » : c'est la régression innocente.
Dépendance aux experts
Une question simple nécessite de déranger l'expert. L'expert devient un goulot d'étranglement. Frustration des deux côtés, turn-over accéléré.
Incidents qui se répètent
Sans postmortem (l'analyse écrite après un incident) documenté, les mêmes incidents surviennent encore et encore. L'équipe ne capitalise pas sur ses erreurs.
Le Bus Factor : votre vulnérabilité cachée
Section intitulée « Le Bus Factor : votre vulnérabilité cachée »Le Bus Factor (ou « lottery factor » pour être moins morbide) est le nombre de personnes qui, si elles disparaissaient demain, mettraient votre projet en péril. Si ce nombre vaut 1, vous avez un problème sérieux.
Le schéma suit la chaîne de risque : un seul expert détient la connaissance tacite, ce savoir est exposé aux absences et aux pics d'activité, et la seule parade durable consiste à le documenter.
J'ai travaillé dans une équipe où un développeur senior était le seul à comprendre le système de facturation. Il connaissait tous les workarounds, tous les cas particuliers, toutes les configurations legacy. Quand il est parti pour un autre poste, l'équipe a découvert que :
- Des scripts critiques n'étaient pas versionnés
- Des procédures existaient uniquement sous forme orale (« tu fais comme ça, tu verras »)
- Les contacts métier clés n'étaient connus que de lui
- L'historique des incidents était dans sa tête
Trois mois de chaos ont suivi.
Documenter n'est pas un luxe, c'est une assurance
Section intitulée « Documenter n'est pas un luxe, c'est une assurance »Vous n'achetez pas une assurance habitation parce que vous savez que votre maison va brûler. Vous l'achetez parce que si elle brûle, vous ne voulez pas tout perdre. La documentation fonctionne de la même façon : elle vous protège de trois risques, les incidents, le turnover et la croissance de l'équipe.
Un runbook bien écrit permet à n'importe qui dans l'équipe de résoudre un incident connu. Pas besoin d'attendre l'expert. Pas besoin de paniquer. La procédure existe, elle a été testée, elle marche.
Exemple concret : notre runbook "PostgreSQL: connexions saturées" a été utilisé 14 fois en 2024. Temps moyen de résolution : 12 minutes. Sans ce runbook, nous estimons que chaque incident aurait pris 2-3 heures.
Les gens partent. C'est normal. Ce qui n'est pas normal, c'est de perdre des mois de productivité à chaque départ.
Une bonne documentation de service (service overview, une fiche de 2-3 pages qui décrit un service) permet au successeur de comprendre :
- Ce que fait le service et pourquoi
- Ses dépendances et ses consommateurs
- Comment le déployer, le surveiller, le dépanner
- Les décisions architecturales et leurs raisons
Quand l'équipe passe de 3 à 15 personnes, la communication informelle ne suffit plus. Ce qui se transmettait par osmose doit maintenant être formalisé.
La documentation devient le système nerveux de l'équipe : elle véhicule l'information sans avoir besoin que tout le monde parle à tout le monde.
Ce que disent les études
Section intitulée « Ce que disent les études »Je ne vous demande pas de me croire sur parole. Voici ce que disent les études :
-
IDC (International Data Corporation)
Les travailleurs du savoir passent 2,5 heures par jour (30% de leur temps) à chercher des informations. Sur une équipe de 10 personnes, c'est l'équivalent de 3 postes à temps plein perdus en recherche d'information.
-
APQC (American Productivity & Quality Center)
25% du temps des knowledge workers est perdu à cause de « productivity drains », les frictions qui grignotent la productivité. 60% expriment une moindre satisfaction au travail à cause de ces frictions. La documentation structurée réduit ces pertes de 40%.
-
Forrester Research
Les entreprises perdent 30% du temps de leurs employés à chercher des données. Les organisations dotées d'une gestion documentaire mature voient une amélioration de 20% de la productivité.
-
Atlassian (State of Incident Management)
Les équipes avec des runbooks et postmortems documentés ont un MTTR 50% inférieur à celles sans documentation. L'impact est encore plus marqué sur les incidents majeurs.
Le cercle vicieux de la non-documentation
Section intitulée « Le cercle vicieux de la non-documentation »J'ai observé le même schéma dans de nombreuses équipes :
- "Pas le temps de documenter" - L'équipe est débordée, la documentation est repoussée
- L'expertise se concentre - Seuls quelques experts savent vraiment comment ça marche
- Les incidents prennent plus de temps - Sans doc, le diagnostic est plus long
- L'équipe est encore plus débordée - Le temps perdu sur les incidents aggrave la charge
- Retour à l'étape 1 - Encore moins de temps pour documenter
C'est un cercle vicieux. Et le seul moyen d'en sortir est de décider que la documentation n'est pas optionnelle.
Le schéma referme la boucle : chaque étape nourrit la suivante, et la seule flèche qui en sort est une décision, pas un outil ni du temps qui viendrait tout seul.
Comment la documentation sauve des vies (professionnelles)
Section intitulée « Comment la documentation sauve des vies (professionnelles) »Quelques exemples concrets de situations où la documentation a fait la différence :
L'incident du vendredi soir
Section intitulée « L'incident du vendredi soir »Situation : Alerte critique à 19h30, l'expert est déjà parti. Junior seul disponible.
Sans doc : Le junior panique, escalade au manager, qui appelle l'expert sur son mobile. 2 heures perdues avant intervention.
Avec doc : Le junior ouvre le runbook "Service X down", suit les étapes. Service rétabli en 25 minutes. L'expert peut profiter de son week-end.
Le départ de l'architecte
Section intitulée « Le départ de l'architecte »Situation : L'architecte fondateur quitte l'entreprise après 5 ans.
Sans doc : 18 mois pour que l'équipe retrouve une compréhension complète du système. Plusieurs régressions dues à des modifications "innocentes" qui cassaient des invariants non documentés.
Avec doc : ADR expliquant les choix clés, service overviews décrivant les interactions, postmortems listant les pièges connus. Transition en 3 mois.
L'audit de sécurité
Section intitulée « L'audit de sécurité »Situation : Audit externe demande de justifier les choix de sécurité.
Sans doc : Semaines de fouille dans le code et les configs. Justifications approximatives. Écarts (findings) évitables signalés car l'intention n'était pas claire.
Avec doc : ADR de sécurité pointant vers les documents de référence. Audit terminé 40% plus vite. Confiance renforcée.
Le minimum vital à documenter
Section intitulée « Le minimum vital à documenter »Tout documenter est impossible. Voici ce qui compte vraiment :
3 runbooks critiques
Identifiez vos 3 incidents les plus fréquents ou les plus impactants. Créez un runbook pour chacun. C'est le meilleur retour sur investissement possible.
1 checklist déploiement
Une liste de vérification pour vos déploiements en production. Évite les oublis qui causent des incidents.
1 service overview par service critique
Un document de 2-3 pages décrivant ce que fait le service, ses dépendances, comment le déployer et le surveiller.
ADR pour les décisions structurantes
Documentez le pourquoi de vos choix techniques majeurs. Vos successeurs vous remercieront.
Chacun de ces documents a son guide dans la formation : la structure d'un runbook se travaille dans Créer des runbooks efficaces, la fiche de service dans Service overview, et la place de chaque type de document dans la documentation opérationnelle.
La documentation comme culture
Section intitulée « La documentation comme culture »La documentation n'est pas un projet ponctuel. C'est une pratique continue, une culture à construire.
Quelques principes pour y arriver :
-
Intégrer à la Definition of Done
La Definition of Done est la liste des critères qu'une tâche doit remplir pour être considérée comme terminée. Une fonctionnalité n'est pas terminée tant que la documentation n'est pas à jour. C'est non négociable.
-
Attribuer des propriétaires
Chaque document a un responsable nommé. Pas "l'équipe" (qui ne veut dire personne), mais une personne identifiée.
-
Tester la documentation
Faites exécuter vos runbooks par quelqu'un qui ne les a pas écrits. Si ça ne marche pas, réécrivez.
-
Réviser régulièrement
Audit trimestriel des runbooks critiques. Mise à jour après chaque utilisation. Revue annuelle des service overviews.
-
Valoriser l'effort
Reconnaissez le travail de documentation comme vous reconnaissez le code. C'est du travail de qualité qui mérite d'être célébré.
Le propriétaire nommé et la Definition of Done sont détaillés dans Ownership et Definition of Done, et les erreurs classiques qui font mourir une documentation dans les anti-patterns de la documentation. Pour apprendre de chaque incident sans chercher de coupable, le guide des postmortems donne la méthode.
Passez à l'action
Section intitulée « Passez à l'action »Vous êtes convaincu ? Voici votre plan d'action pour les 30 prochains jours :
- Semaine 1 : Identifiez les 3 incidents les plus fréquents de votre équipe
- Semaine 2 : Écrivez le runbook du premier incident
- Semaine 3 : Faites tester ce runbook par un collègue, itérez
- Semaine 4 : Répétez pour les 2 autres incidents
- Mois suivant : Créez votre checklist de déploiement et votre premier service overview
Côté outillage, versionner ces documents dans Git et les relire comme du code, c'est l'approche Docs-as-Code présentée dans Docs-as-Code ; le choix du générateur de site se tranche avec Choisir ses outils de documentation.
À retenir
Section intitulée « À retenir »La documentation n'est pas un livrable de fin de projet : c'est une assurance contre les incidents, les départs et la croissance, qui se construit par petites touches et se vérifie en la faisant exécuter par quelqu'un d'autre.
- Sans runbook, le MTTR d'un incident passe de 20 minutes à 4-8 heures, soit un facteur 10 à 20.
- Le bus factor compte les personnes dont la disparition mettrait le projet en péril ; à 1, le risque est sérieux.
- Documenter, c'est transformer la connaissance tacite en connaissance explicite.
- Le cercle vicieux « pas le temps de documenter » ne se brise que par une décision : la documentation n'est pas optionnelle.
- Le minimum vital : 3 runbooks critiques, 1 checklist de déploiement, 1 service overview par service critique et des ADR pour les décisions structurantes.
- Une documentation vit quand elle entre dans la Definition of Done, a un propriétaire nommé, est testée par quelqu'un qui ne l'a pas écrite et révisée régulièrement.
Contrôle de connaissances
Section intitulée « 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
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
Lance le quiz et démarre le chronomètre
Vérification
(0/0)Score par domaine
Un domaine regroupe plusieurs guides et reçoit plusieurs questions : son score est plus fiable qu'un score par thème, qui porte souvent sur une seule question.
Bilan
Points forts
Aucun sujet réussi à 80 % sur au moins deux questions pour l’instant.
Points faibles
Aucun sujet sous le seuil de réussite.
À faire ensuite
Des indices pour retenter votre chance ?
Continuer le cours : Choisir le bon document : tutoriel, guide, référence ou explication
Nouveau quiz complet avec des questions aléatoires
Retravailler uniquement les questions ratées
Retour à la liste des certifications
Références externes
Section intitulée « Références externes »Ces sources étayent les chiffres cités dans la page et prolongent la réflexion : le MTTR côté Atlassian, la recherche d'information côté IDC et APQC, et les bonnes pratiques de la communauté Write the Docs.
- Google SRE Book : Chapter 8 - Release Engineering (documentation des processus)
- Atlassian : Incident Management Best Practices (MTTR, MTTA)
- IDC Study : The Knowledge Worker's Day
- APQC : Knowledge Management Best Practices
- Write the Docs : Documentation Guide (communauté et bonnes pratiques)