La page que vous ouvrez à 3 h du matin
est celle que personne n'a lue depuis qu'elle a été écrite.
L’incident commence. Quelqu’un trouve le runbook, et la troisième étape renvoie à un tableau de bord retiré du service, à un script déplacé et à l’alias d’une équipe qui n’existe plus. Rien de tout cela n’était visible hier.
Les runbooks se dégradent autrement que le reste de la documentation. Une spécification périmée est lue par quelqu’un qui a le temps de s’en apercevoir ; un runbook est lu sous pression par la personne d’astreinte, souvent pour la première fois, et chaque ligne fausse coûte des minutes au pire moment.
Le vrai problème, c’est que personne ne sait quels runbooks sont fiables. Non que l’information manque — mais rien ne la rassemble. Qui a lu celui-ci depuis sa dernière réécriture ? Ses liens aboutissent-ils encore ? Le service qu’il décrit a-t-il changé depuis ?
« Trois des cinq ingénieurs d’astreinte ont lu la version actuelle » : vous ne pouvez le dire que si la lecture a été comptée par version plutôt que par document.
Les parties qui comptent ici
Pas toute la liste des fonctionnalités — celles dont dépend ce problème précis.
Des accusés de lecture fiables
Comptés après dix secondes de lecture visible, jamais sur un clic dans l’arborescence, et seulement pour la version actuelle. Réécrivez le runbook et le compteur repart de zéro, car ceux qui ont lu l’ancien n’ont pas lu celui-ci.
Des liens cassés, trouvés avant l’incident
Un lien relatif qui ne mène à aucun document est un constat, recalculé à partir du corpus plutôt que consigné une fois puis oublié. Il cesse d’être un constat quand il cesse d’être vrai.
L’obsolescence mesurée sur le contenu, pas sur les dates
Mesurée depuis la dernière vraie modification du contenu : un fichier que le worker de synchronisation a touché pour une autre raison ne paraît pas récent. Un repository tout juste connecté ne signale aucune obsolescence, et l’écran le dit au lieu de laisser croire que tout va bien.
La documentation en retard sur le code
Un runbook qui cite un chemin source modifié après lui est le seul signal du produit qui relie le code à la documentation — et ce qui se rapproche le plus d’une alerte précoce.
Une recherche sur tous les services
Être d’astreinte sur une plateforme, c’est l’être pour des services que vous n’avez pas écrits. Une seule touche lance la recherche dans chaque repository connecté, pas seulement dans celui que vous avez ouvert.
Copy for LLM, en plein incident
Transmettez le runbook et ses voisins à un modèle en markdown propre, avec le nombre de tokens avant de coller. C’est pour cela qu’on ouvre un runbook dans un second onglet, et cela prend une action au lieu de six.
Ce qui se passe réellement
- 01Connectez les repositories couverts par la rotation d’astreinteGénéralement plusieurs, car une rotation correspond rarement à un seul service. Ils arrivent dans un même projet et la recherche les couvre tous.
- 02L’analyse de santé trouve ce qui est déjà casséDes liens relatifs cassés, des documents dont le contenu n’a pas changé depuis plus longtemps que votre seuil, et des documents citant des fichiers source qui ont bougé après eux. Rien de tout cela n’appelle un modèle, donc rien ne coûte quoi que ce soit.
- 03Quelqu’un écarte les constats erronésLe rejet est la seule chose durable ici — il survit au recalcul et absorbe sa propre redécouverte, si bien que le même faux positif ne revient pas à chaque passage.
- 04L’équipe valide les runbooks à jourUn état de relecture sur chacun, fixé sur le texte exact. Désormais, fiable et non trié ne se ressemblent plus dans l’arborescence.
- 05Un service change, le runbook nonLe push a touché un chemin source que le runbook cite. Le constat apparaît sans que personne ne le signale, et le badge validé indique dérivé.
- 06L’incident survient et la page est justeOu elle est fausse d’une manière que quelqu’un connaissait déjà — c’est la version réaliste de cette promesse, et celle qui vaut d’être payée.
Ce que cela ne résout pas
Chaque page de ce site en porte une, pour la même raison : une page de cas d'usage sans limite est une brochure.
- Il ne vérifie pas les étapes
- Nous pouvons vous dire qu’un lien est cassé et que le code a bougé. Nous ne pouvons pas vous dire si l’étape quatre fonctionne encore — seule son exécution le peut.
- Ce n’est pas un outil de gestion d’incidents
- Pas d’alertes, pas d’appels d’astreinte, pas de chronologie, pas de modèle de postmortem. Il se place à côté de ces outils ; il ne les remplace pas.
- L’obsolescence est un seuil que vous choisissez
- Aucun modèle ne décide de ce que signifie « ancien ». Un runbook pour quelque chose qui ne change jamais n’est pas obsolète à quatre-vingt-dix jours, et vous seul savez lesquels.