Pourquoi la documentation d'architecture compte pour les équipes modernes
Laissez-moi vous raconter le pire trimestre de ma carrière d'ingénieur.
C'était en 2019. J'étais le tech lead de l'équipe plateforme core d'une startup fintech. Nous avions une belle architecture microservices — 23 services, event-driven, proprement isolés. Le système ronronnait tranquillement. On savait exactement comment tout fonctionnait.
Puis trois choses se sont passées en succession rapide :
- Sarah, notre ingénieure principale, est partie pour une entreprise FAANG
- Marcus, qui avait construit notre intégration de paiement, s'est fait débaucher par un concurrent
- Lisa, la seule personne qui comprenait notre service de réconciliation legacy, est partie en congé maladie prolongé
En six mois, la moitié des connaissances institutionnelles sur notre architecture a franchi la porte. Et nous n'avions presque pas de documentation.
Ce qui a suivi a été des mois de reverse-engineering de nos propres systèmes. Des fonctionnalités qui auraient dû prendre une semaine prenaient un mois parce qu'on devait d'abord comprendre comment le code existant fonctionnait. On a introduit des bugs parce qu'on ne comprenait pas les raisons subtiles derrière certaines décisions de conception. On a fait des changements architecturaux qui entraient en conflit avec des contraintes qu'on avait oubliées.
Cette expérience m'a converti de sceptique de la documentation à évangéliste de la documentation. Non pas parce que j'ai soudainement aimé écrire des docs, mais parce que j'ai vu de mes propres yeux ce qui se passe sans elles.
Le vrai coût de la documentation manquante
Soyons honnêtes sur ce que coûte une mauvaise documentation. Pas en termes vagues de "c'est important", mais en impact concret que j'ai constaté.
Temps d'onboarding
Dans cette fintech, les nouveaux ingénieurs mettaient 4-6 mois pour devenir productifs. Non pas parce qu'ils n'étaient pas intelligents — ils étaient excellents — mais parce que comprendre notre système nécessitait d'absorber des années de connaissances tribales par osmose.
Après avoir investi dans la documentation, ça a chuté à 6-8 semaines. Même calibre d'ingénieurs, même complexité du système. La seule différence était qu'ils avaient une carte au lieu d'errer à l'aveugle.
Le calcul est simple. Si vous embauchez 5 ingénieurs par an et que chacun perd 3 mois à se mettre à niveau, ça fait 15 mois-personnes perdus annuellement. Aux salaires d'ingénieurs seniors, vous regardez un quart de million de dollars en productivité perdue — chaque année.
Latence des décisions
Sans documentation, chaque discussion architecturale repart de zéro.
"Pourquoi utilise-t-on Kafka ici au lieu de RabbitMQ ?"
Personne ne sait. Discutons pendant deux heures.
"Peut-on ajouter un appel synchrone du Service A au Service B ?"
Ça dépend d'une contrainte qui pourrait exister. Passons une journée à enquêter.
"Que se passe-t-il si le service de paiement tombe ?"
Bonne question. Traçons à travers le code pendant une semaine.
Quand le contexte architectural est documenté, ces questions ont des réponses. Pas toujours des réponses immédiates, mais au moins vous savez où chercher. Les cycles de décision passent de semaines à jours.
Réponse aux incidents
2h du matin. Le pager sonne. Le flux de checkout échoue. Vous êtes l'ingénieur d'astreinte, et vous n'êtes dans l'entreprise que depuis deux mois.
Sans documentation, vous grepez frénétiquement à travers le code, essayant de comprendre le système pendant qu'il est en feu. Vous pingez des canaux Slack en espérant que quelqu'un qui connaît le flux de paiement soit réveillé.
Avec documentation, vous ouvrez l'architecture du système, voyez comment le flux de checkout fonctionne, identifiez quels services sont impliqués, et savez où chercher le problème. Vous pourriez même trouver un runbook de dépannage pour exactement ce scénario.
J'ai été des deux côtés de ça. La différence en temps moyen de résolution est dramatique.
Accumulation de dette technique
Voici un pattern que j'ai vu à plusieurs reprises :
- Une équipe construit un système bien architecturé
- La documentation n'existe pas ou devient obsolète
- De nouveaux ingénieurs rejoignent, ne comprennent pas l'architecture
- Ils ajoutent des fonctionnalités qui violent les principes architecturaux
- La dette technique s'accumule
- Finalement, quelqu'un propose une réécriture
La réécriture n'est pas toujours nécessaire. Souvent, l'architecture originale était correcte — elle n'était juste pas comprise. Sans documentation, chaque principe architectural est à une rotation d'équipe d'être oublié.
À quoi ressemble vraiment une bonne documentation
Documenter pour documenter est inutile. J'ai vu des équipes produire des centaines de pages de docs que personne ne lit. La clé est de documenter les bonnes choses de la bonne façon.
Documenter le pourquoi, pas seulement le quoi
Le code montre ce que fait le système. La documentation devrait expliquer pourquoi.
Pourquoi avons-nous choisi PostgreSQL plutôt que MongoDB ? Pourquoi ces services sont-ils séparés au lieu d'être combinés ? Pourquoi cet endpoint accepte-t-il ce format particulier ?
Ces questions "pourquoi" ont des réponses qui ne sont pas dans le code. Elles sont dans la tête des personnes qui ont pris les décisions. Si vous ne les écrivez pas, elles sont perdues quand ces personnes partent.
La rendre découvrable
La meilleure documentation est inutile si personne ne peut la trouver. Notre fintech avait en fait un peu de documentation — enterrée dans un espace Confluence qui n'était lié nulle part, avec une fonction de recherche qui marchait à peine.
La documentation devrait être :
- Liée depuis le code (fichiers README, commentaires de code avec liens vers les docs)
- Organisée logiquement (pas juste déversée chronologiquement)
- Recherchable (recherche full-text à travers tous les docs)
On a finalement déplacé notre documentation d'architecture dans le repository lui-même. Maintenant elle apparaît dans les revues de code, est versionnée avec le code, et ne peut pas trop dériver de la réalité.
La rendre maintenable
La documentation qui est pénible à mettre à jour ne se met pas à jour.
C'est pourquoi je suis sceptique des diagrammes UML élaborés. Ils sont beaux quand ils sont créés et désespérément obsolètes six mois plus tard parce que les mettre à jour nécessite des outils et des compétences spécialisés.
Les formats simples fonctionnent mieux :
- Markdown que n'importe qui peut éditer
- Diagrammes en texte (Mermaid, PlantUML) qui vivent à côté du code
- Diagrammes C4 qui sont intentionnellement simples à maintenir
La documentation qui est maintenue est la documentation qui est facile à maintenir.
Cibler plusieurs audiences
Différentes personnes ont besoin de différents niveaux de détail.
Un nouvel ingénieur a besoin d'une vue d'ensemble du système. Un product manager a besoin de comprendre les frontières des services. Un architecte a besoin de voir les relations entre composants. Un ingénieur d'astreinte a besoin d'informations opérationnelles.
Le modèle C4 fonctionne bien ici car il fournit explicitement différents niveaux de zoom. Contexte système pour les dirigeants, diagrammes de containers pour les architectes, diagrammes de composants pour les développeurs.
Étapes pratiques pour commencer à documenter
Si vous partez de zéro, voici l'approche que j'ai trouvée qui fonctionne :
Semaine 1 : Contexte Système
Passez quelques heures à créer un diagramme qui montre :
- Votre système comme une seule boîte
- Qui l'utilise
- À quels systèmes externes il se connecte
Rien que ça a de la valeur. Ça établit les frontières et donne aux nouveaux membres de l'équipe un point de départ.
Semaine 2 : Diagramme de Containers
Décomposez votre système en ses pièces déployables :
- Services, applications, bases de données
- Comment ils communiquent
- Quelles technologies ils utilisent
Ça devient la référence pour les discussions d'infrastructure et l'onboarding.
Semaine 3 : Décisions clés
Documentez vos trois décisions architecturales les plus importantes :
- Ce qui a été décidé
- Pourquoi ça a été décidé
- Quelles alternatives ont été considérées
Ça empêche de relitiger d'anciens débats et aide les nouveaux membres de l'équipe à comprendre la raison derrière la forme du système.
Pour la suite : Partie du workflow
La documentation initiale est la partie facile. La maintenir à jour est plus difficile.
Faites de la documentation une partie de votre définition du done. Si une PR change l'architecture, elle devrait mettre à jour les docs pertinentes. Ça n'arrive pas automatiquement — ça nécessite de la discipline dans les revues et un engagement culturel.
Certaines équipes ajoutent des checks automatisés : un job CI qui vérifie que les fichiers README existent, ou un template de PR qui demande "Ce changement modifie-t-il l'architecture ? Si oui, avez-vous mis à jour les docs ?"
Le défi culturel
Je vais être honnête : faire documenter une équipe est souvent une bataille culturelle.
Les ingénieurs préfèrent généralement écrire du code plutôt que des docs. La documentation ressemble à de l'overhead, pas à de l'output. Quand les deadlines approchent, les docs sont la première chose coupée.
Ce que j'ai trouvé qui aide :
Rendre ça personnel
Quand un nouvel ingénieur rejoint, demandez-lui de documenter ce qu'il apprend pendant qu'il s'intègre. Il voit le système avec des yeux neufs et remarque des lacunes que les anciens ratent. En plus, il bénéficie directement d'avoir la documentation qu'il aurait aimé avoir.
Célébrer la documentation
Mentionnez les mises à jour de documentation dans les sprint reviews. Reconnaissez les ingénieurs qui maintiennent de bons docs. Rendez visible que la documentation est valorisée, pas juste tolérée.
Automatiser ce qu'on peut
Moins il y a de documentation manuelle requise, plus elle a de chances d'arriver. Utilisez des outils qui génèrent des docs à partir du code. Utilisez l'IA pour créer des premiers brouillons. Utilisez des diagrammes-as-code qui se mettent à jour automatiquement.
C'est en partie pourquoi j'ai construit Archyl. L'overhead manuel de création et maintenance de documentation d'architecture est une barrière majeure. La découverte assistée par IA et l'édition visuelle réduisent cette barrière.
Connecter ça à la douleur
Les gens changent de comportement quand ils ressentent la douleur. La prochaine fois que quelqu'un passe des jours à comprendre un système parce qu'il n'y a pas de documentation, faites-le remarquer. "Ça aurait pu être une tâche d'une heure si on avait des docs."
Conclusion
La documentation n'est pas excitante. Ce n'est pas la raison pour laquelle aucun d'entre nous s'est lancé dans l'ingénierie logicielle. Mais c'est la différence entre un système qui survit à ses créateurs et un qui devient un désordre inmaintenable.
La fintech que j'ai mentionnée plus tôt ? Après cette période douloureuse, on a investi sérieusement dans la documentation. Diagrammes d'architecture, decision records, runbooks, tout le toutim. Ça a pris environ six mois d'effort dédié.
La fois suivante où quelqu'un est parti, ça a à peine perturbé l'équipe. Leurs connaissances étaient dans le système, pas juste dans leur tête.
C'est ce qu'est vraiment la documentation : une assurance contre la perte de connaissances. Et comme toute assurance, elle semble chère jusqu'à ce que vous en ayez besoin.
Continuez votre parcours de documentation : Introduction au modèle C4 | Architecture Decision Records | Documenter les flux utilisateurs