Chronologie : de l'enthousiasme à l'abandon
Le 8 avril 2025, après une session de threat-model où nous avons identifié la dérive de documentation comme un risque majeur, nous avons décidé d'adopter une approche docs-as-code. L'équipe était unanime : nos runbooks Word hébergés sur SharePoint n'étaient jamais à jour, et les incidents récents avaient révélé un écart croissant entre nos procédures documentées et la réalité de production. Nous avons investi deux semaines de sprint pour mettre en place un repo Git dédié, configurer des tests automatisés de validation des exemples de code, et former l'équipe sur Markdown et les conventions de commit.
Les premières semaines ont été prometteuses. Entre le 22 avril et le 15 mai, nous avons migré 47 documents critiques, créé des templates standardisés, et implémenté un workflow de revue par les pairs. Chaque pull request de code incluait désormais une mise à jour obligatoire de la documentation correspondante. Nous avions même configuré un bot Slack qui postait automatiquement les mises à jour de docs dans un canal dédié. Le système technique fonctionnait parfaitement : nos tests validaient que les exemples de configuration YAML étaient syntaxiquement corrects, les liens internes étaient vérifiés automatiquement, et le site statique se générait en moins de deux minutes.
Editor associe expertise technique et passion du détail dans tout ce qu'elle écrit sur Création d'entreprise
Le déclin a commencé fin mai. Les ingénieurs ont progressivement cessé de consulter le site de documentation. Lors d'un incident majeur le 3 juin concernant une dégradation de p99 latency sur notre API de facturation, l'équipe d'astreinte a passé 35 minutes à chercher la procédure de rollback alors qu'elle était pourtant documentée et à jour dans notre système docs-as-code. Ils ont finalement trouvé la solution dans un message Slack archivé de trois mois. Le 28 juin, notre audit interne a révélé que seulement 12 % des accès au site de documentation provenaient d'ingénieurs en situation réelle ; le reste était constitué d'auteurs vérifiant leurs propres contributions.
Ce que nous croyions : les hypothèses fondamentales
Notre stratégie reposait sur trois convictions fortes que nous pensions validées par l'industrie. Premièrement, nous croyions que versionner la documentation avec Git garantirait sa synchronisation avec le code. Si chaque changement de comportement système nécessitait une mise à jour de doc dans la même PR, alors mathématiquement, les specs resteraient alignées. Deuxièmement, nous étions persuadés que tester automatiquement les exemples de code éliminerait le problème classique des snippets obsolètes qui ne compilent plus. Nos tests validaient la syntaxe YAML, vérifiaient les chemins de fichiers mentionnés, et s'assuraient que les commandes shell retournaient un exit code zéro.
Troisièmement, nous avions adopté le principe que la documentation devait vivre au plus près du code. Backstage et d'autres plateformes de developer portal prônent cette approche : chaque service possède un dossier docs/ dans son repo, et un système central agrège tout pour générer un site unifié. Nous pensions qu'en réduisant la friction de contribution, les développeurs maintiendraient naturellement leurs docs. Cette conviction était renforcée par des success stories lues dans des blogs d'ingénierie de grandes entreprises tech, où l'approche docs-as-code avait transformé la culture documentaire.
- Conviction 1 : Git comme source de vérité unique garantit l'alignement documentation-code
- Conviction 2 : Les tests automatisés éliminent les exemples obsolètes et cassés
- Conviction 3 : Réduire la friction d'écriture augmente automatiquement la qualité et la fraîcheur
- Conviction 4 : Un processus de revue par les pairs assure la précision technique
- Conviction 5 : Markdown et Git sont des outils familiers qui facilitent l'adoption
Ces hypothèses n'étaient pas absurdes en elles-mêmes. Elles sont effectivement valides dans certains contextes. Notre erreur a été de ne pas questionner leurs limites ni d'identifier les conditions préalables nécessaires à leur succès. Nous avons traité docs-as-code comme une solution universelle alors qu'il s'agit d'un outil avec un domaine d'application spécifique. Nous n'avons jamais formalisé explicitement pourquoi nos ingénieurs consultaient Slack plutôt que SharePoint, et nous avons présumé que le problème était uniquement technique.
Ce qui s'est réellement passé : l'usage en conditions réelles
La première faille est apparue autour de la découvrabilité. Notre site de documentation généré statiquement avait une barre de recherche, une taxonomie logique par services, et des tags. Pourtant, quand un ingénieur d'astreinte à 3h du matin cherchait comment débloquer une queue depth excessive sur RabbitMQ, son premier réflexe était de taper dans Slack ou de consulter ses notes personnelles. La raison était simple mais dévastatrice : le contexte de recherche différait fondamentalement de la structure de nos docs. Nous avions organisé la documentation par architecture logique, mais les gens cherchaient par symptôme.
La documentation parfaite qui n'est jamais trouvée au moment critique ne vaut rien.
Le deuxième problème concernait la granularité et le format. Nos runbooks d'origine, bien qu'obsolètes, contenaient des décisions contextuelles et des notes d'expérience : « Attention, ne pas redémarrer le service avant de vider le cache Redis, sinon le cold start provoque un effet noisy neighbour sur les autres pods. » Ces insights critiques ne survivaient pas au passage en Markdown structuré. Nos templates standardisés privilégiaient la cohérence formelle au détriment de la richesse contextuelle. Les ingénieurs seniors qui avaient cette connaissance tacite ne prenaient pas le temps de la formaliser dans une structure rigide.
Le troisième échec était plus subtil : le décalage temporel entre écriture et validation. Dans notre workflow, un auteur écrivait la doc, un reviewer la validait techniquement, puis elle était publiée. Mais personne ne la testait en conditions réelles avant qu'un incident ne survienne. Nous avons découvert lors du postmortem du 3 juin que la procédure de rollback documentée omettait une étape critique introduite trois mois plus tôt : vérifier que le feature flag dans notre système de canary deploy était bien désactivé avant le rollback, sinon le trafic continuait d'être routé vers l'ancienne version. Cette étape existait dans la pratique, mais n'avait jamais été capturée par écrit.
Analyse des causes profondes
En appliquant une analyse root cause rigoureuse, nous avons identifié quatre facteurs déterminants. Le premier était un problème d'incitation mal alignée. Écrire de la documentation prenait du temps, mais aucune métrique de performance individuelle ne valorisait cette contribution. Les développeurs étaient évalués sur la vélocité de livraison de fonctionnalités et la réduction du change failure rate. Maintenir des docs n'apparaissait nulle part dans les objectifs trimestriels. Même avec un processus obligatoire de mise à jour dans chaque PR, la qualité minimale pour passer la revue était faible.
Le deuxième facteur était architectural. Nous avions construit un système centré sur les auteurs, pas sur les lecteurs. La priorité était de faciliter l'écriture et le versionnement, mais nous n'avions jamais mesuré l'efficacité de la recherche ni le temps moyen pour trouver une information en situation d'incident. Nos métriques de succès étaient le nombre de pages migrées, le taux de mise à jour des docs par sprint, et le temps de génération du site. Aucune ne capturait la valeur réelle : est-ce que quelqu'un trouve rapidement la bonne réponse quand ça compte ?
Le piège de l'automatisation sans validation empirique
Nous avons surinvesti dans l'automatisation technique avant de valider que le système résolvait le problème humain. Nos tests vérifiaient que les commandes shell s'exécutaient, mais pas qu'elles produisaient le résultat attendu dans le contexte d'un incident réel. Un exemple concret : notre doc de dépannage pour les alertes de SLI dégradé incluait une commande curl pour interroger l'API de métriques. Le test automatisé validait que curl retournait un code 200, mais en production, cette API nécessitait un token d'authentification qui n'était pas documenté, car il était considéré comme « évident » par l'auteur.
- Nous avons optimisé le processus d'écriture sans mesurer l'efficacité de lecture ni l'utilisabilité en situation de stress
- Nous avons présumé que la synchronisation Git-code garantissait la pertinence sans valider empiriquement que les docs étaient consultés
- Nous avons ignoré le fait que la connaissance critique vit souvent dans les échanges informels, pas dans les procédures formelles
- Nous n'avons pas reconnu que la documentation d'incident nécessite une organisation par symptôme, pas par architecture
Leçons apprises et changements implémentés
La première leçon majeure : la documentation d'incident et la documentation de référence sont deux artefacts distincts avec des besoins opposés. La doc de référence bénéficie effectivement de docs-as-code, versioning, tests automatisés. Mais les runbooks d'incident ont besoin d'une approche différente : organisation par symptôme, exemples enrichis de contexte décisionnel, validation par simulation d'incident, et surtout une découvrabilité optimisée pour des humains stressés à 3h du matin. Nous avons depuis séparé ces deux corpus et adopté un wiki structuré pour les runbooks, avec des liens bidirectionnels vers la doc technique versionnée.
Deuxième leçon : l'automatisation des tests de documentation doit valider le résultat attendu en contexte réel, pas juste la syntaxe. Nous avons réécrit nos tests pour qu'ils s'exécutent dans un environnement de staging qui réplique les permissions, les configurations réseau, et les dépendances de production. Un test qui valide un runbook doit simuler l'exécution complète de la procédure et vérifier que le système atteint l'état désiré. C'est plus coûteux à maintenir, mais c'est la seule façon de garantir que la doc fonctionne quand on en a besoin.
Troisième leçon : mesurer l'usage réel, pas l'effort de production. Nous avons implémenté un système de feedback direct dans chaque page de doc : « Cette procédure vous a-t-elle aidé à résoudre votre problème ? » avec une option pour signaler les manques. Nous suivons désormais le nombre de fois qu'une page est consultée pendant un incident actif versus en temps normal, et nous priorisons les mises à jour en fonction de cette métrique. Nous avons également instauré une revue mensuelle des docs lors de notre weekly incident review, où nous identifions les lacunes révélées par les incidents récents.
Quatrièmement, nous avons reconnu que la connaissance tacite ne se capture pas spontanément. Nous avons créé un rituel trimestriel où les ingénieurs seniors enregistrent des sessions de partage de connaissances sur les décisions architecturales, les pièges connus, et les contextes décisionnels. Ces enregistrements sont transcrits et intégrés dans les docs comme des sections « Contexte et décisions historiques ». Cette approche hybride capture la richesse du contexte tout en maintenant une structure recherchable.
Ce que nous faisons différemment maintenant
Notre nouveau système articule trois niveaux de documentation avec des outils adaptés à chaque usage. Les API references et les specs techniques vivent dans Git avec docs-as-code, tests automatisés, et génération de sites statiques. Les runbooks d'incident sont dans un wiki structuré avec recherche par symptôme, tags de blast radius, et historique des incidents associés. La connaissance tacite et les décisions architecturales sont capturées dans un système de knowledge base avec transcriptions de sessions de partage et liens vers les discussions Slack archivées.
Nous avons également changé notre définition de done pour les incidents. Un incident n'est considéré résolu que lorsque le runbook correspondant a été mis à jour et validé par une simulation dans l'environnement de staging. Cette contrainte a transformé la maintenance de documentation d'une corvée optionnelle en partie intégrante du processus de résolution. Nous suivons maintenant notre MTTR de documentation : le temps entre la détection d'un gap documentaire et sa correction validée. Cette métrique est aussi importante que notre change failure rate dans nos north-star definitions d'équipe.
Enfin, nous avons accepté que documentation parfaite n'existe pas. L'objectif n'est pas d'avoir des specs exhaustives et toujours à jour, mais d'avoir un système qui se répare rapidement quand on découvre un manque. Nous publions un weekly metrics digest qui inclut les gaps documentaires identifiés, les pages les plus consultées pendant les incidents, et les feedbacks négatifs. Cette transparence a créé une boucle d'amélioration continue où l'équipe comprend la valeur directe de maintenir les docs.
Réflexions finales : au-delà de la technique
Cet échec nous a enseigné que les problèmes de documentation ne sont jamais purement techniques. Docs-as-code est un excellent outil pour certains types de contenu, mais ce n'est pas une solution universelle. Le vrai défi n'était pas de versionner du Markdown dans Git, mais de créer un système qui aide réellement les gens à trouver rapidement les bonnes réponses quand ils en ont besoin. Cette distinction semble évidente rétrospectivement, mais nous l'avons complètement manquée pendant trois mois en nous concentrant sur l'élégance de notre infrastructure technique.
Si nous devions recommencer aujourd'hui, nous commencerions par observer comment les ingénieurs cherchent actuellement l'information en situation de stress, puis nous construirions un système autour de ces comportements réels plutôt que d'imposer un workflow idéal. Nous mesurerions l'efficacité de la découverte avant d'investir dans l'automatisation de la production. Et surtout, nous reconnaitrions que la documentation vivante ne vient pas de l'infrastructure technique, mais d'un engagement organisationnel à valoriser et mesurer cette contribution. L'échec de notre système docs-as-code n'était pas un échec d'ingénierie, mais un échec de compréhension des besoins réels de nos utilisateurs. Une leçon coûteuse, mais fondamentale pour tout ce que nous construisons maintenant.