Mise à jour :
Il est 3h du matin. L’alerte PagerDuty vous réveille en sursaut. Le service de paiement est down. Votre collègue expert sur ce service ? En vacances au Népal, sans réseau. Vous ouvrez votre laptop, cherchez de la documentation… et vous ne trouvez rien. Pas de runbook, 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.
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 graphique ci-dessus illustre la différence fondamentale entre deux approches :
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.
Au-delà du MTTR, le manque de documentation génère des coûts que personne ne mesure :
Onboarding ralenti
Un nouveau 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 par interruption (étude Microsoft).
Décisions mal informées
Sans ADR (Architecture Decision Records), les nouveaux refont les mêmes erreurs 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”.
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 documenté, les mêmes incidents surviennent encore et encore. L’équipe ne capitalise pas sur ses erreurs.
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 est 1, vous avez un problème sérieux.
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 :
Trois mois de chaos ont suivi.
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 :
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) permet au successeur de comprendre :
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.
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”. 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 avec 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.
J’ai observé le même schéma dans de nombreuses équipes :
C’est un cercle vicieux. Et le seul moyen d’en sortir est de décider que la documentation n’est pas optionnelle.
Quelques exemples concrets de situations où la documentation a fait la différence :
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.
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.
Situation : Audit externe demande de justifier les choix de sécurité.
Sans doc : Semaines de fouille dans le code et les configs. Justifications approximatives. 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.
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 ROI 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.
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
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. Review 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é.
Vous êtes convaincu ? Voici votre plan d’action pour les 30 prochains jours :
