Un logiciel legacy tient souvent grâce à quelques personnes. Elles savent pourquoi un statut ne doit jamais être modifié le vendredi, quelle table ne reflète pas la réalité métier, quel export sert à la clôture, quel traitement peut être relancé et quelle règle historique ne figure dans aucune documentation.
Tant que ces personnes sont disponibles, le risque reste discret. Le projet avance, les incidents se règlent, les anomalies trouvent une explication. Mais dès qu’un départ, une mobilité interne ou une indisponibilité arrive, l’application devient plus fragile que son code ne le montre.
Un audit technique application web doit donc capter le savoir des sachants avant de juger uniquement l’architecture. La documentation utile n’est pas un inventaire exhaustif. C’est une carte exploitable des règles, données, flux, incidents et décisions qui permettent de reprendre l’application.
Dans une migration application legacy vers Symfony, cette étape évite de reconstruire un système incompris. Elle permet de moderniser sans perdre les raisons qui ont façonné l’existant.
Pourquoi la documentation devient urgente
La documentation d’un legacy devient urgente quand la connaissance n’est plus partagée. Le risque n’est pas seulement de perdre une explication. C’est de perdre la capacité à distinguer une anomalie, une règle volontaire, une dette assumée et une dépendance historique.
Une équipe peut lire le code, parcourir la base et consulter les tickets. Mais sans les personnes qui comprennent les compromis passés, elle risque d’interpréter trop vite. Ce qui paraît incohérent peut être une protection. Ce qui paraît indispensable peut être un reste obsolète.
Le départ d’un sachant transforme la dette en risque actif
Une zone peu documentée n’est pas forcément critique si plusieurs personnes savent la maintenir. Elle devient critique quand une seule personne sait pourquoi elle fonctionne ainsi.
La priorité de documentation doit donc suivre la concentration du savoir. Plus une zone dépend d’une personne, plus elle doit être capturée tôt.
Documenter trop tard coûte plus cher
Après le départ, l’équipe compense par des investigations longues, des hypothèses, des extractions de données et des essais prudents. Cette reconstruction est lente, parfois incomplète, et elle augmente le risque de corriger au mauvais endroit.
Documenter avant le départ transforme une connaissance fragile en actif projet. Ce n’est pas administratif. C’est une mesure de continuité.
Identifier le savoir vraiment critique
Toute connaissance n’a pas la même valeur. Le but n’est pas de demander aux sachants de tout raconter. Il faut identifier les zones où leur mémoire protège le run, les données, les clients, la conformité ou la roadmap.
Un savoir est critique quand son absence bloque une correction, rend une donnée inexplicable, empêche une recette, ralentit une migration ou crée une dépendance forte à un ancien comportement.
Commencer par les zones qui font peur
Les équipes savent souvent nommer les zones à éviter : vieux batch, écran sensible, export fragile, règle de calcul obscure, import historique, module de droits, passerelle partenaire ou traitement de clôture.
Ces zones méritent une session de capture dédiée. Il faut comprendre ce qu’elles font, ce qui les rend risquées, comment elles échouent et quelles personnes savent encore les réparer.
Classer le savoir par usage
Un bon classement distingue savoir métier, savoir technique, savoir de données, savoir d’exploitation et savoir d’historique. Cette séparation aide les futurs repreneurs à trouver rapidement l’information utile.
Une règle métier explique pourquoi une décision existe. Une note technique explique comment elle est implémentée. Une note de run explique quoi faire quand elle échoue. Les trois ne remplacent pas les unes les autres.
Capturer les règles métier implicites
Les règles implicites sont souvent le cœur du legacy. Elles ne sont plus discutées, mais elles structurent les écrans, les validations, les exports, les emails, les contrôles et les exceptions.
Il faut documenter la règle, son intention, ses exceptions, ses propriétaires et les cas où elle ne s’applique pas. Une règle sans contexte devient difficile à faire évoluer.
Une règle doit être reliée à une décision
Au lieu d’écrire seulement “ce statut bloque la facturation”, il faut expliquer quelle décision est protégée : éviter une facturation incomplète, attendre une validation, empêcher un doublon ou conserver une preuve.
Cette intention permettra plus tard de moderniser la règle sans la copier aveuglément.
Les exceptions doivent être visibles
Les exceptions sont souvent connues oralement. Elles expliquent pourquoi un parcours accepte parfois une donnée vide, un changement manuel, une validation tardive ou un contrôle différent.
Les documenter évite deux erreurs opposées : supprimer une exception encore nécessaire ou conserver une exception devenue inutile.
Documenter données, statuts et historiques
Les données révèlent la mémoire du système. Un champ peut avoir changé de sens, un statut peut être réutilisé, un identifiant peut venir d’un ancien outil, un historique peut être incomplet pour une bonne raison.
Documenter un legacy sans cartographier les données revient à décrire les écrans sans comprendre ce qu’ils manipulent réellement.
Les statuts méritent une attention spéciale
Un statut porte souvent plus qu’un libellé. Il indique une responsabilité, un niveau de contrôle, une possibilité d’action, une visibilité client, une conséquence comptable ou une étape de synchronisation.
La documentation doit préciser qui peut changer le statut, dans quelles conditions, avec quelle donnée obligatoire et quelle conséquence sur les autres systèmes.
Les historiques ne sont pas toujours fiables de la même manière
Certains historiques sont opposables. D’autres servent seulement au diagnostic. D’autres encore sont partiels parce qu’un ancien traitement n’écrivait pas tout.
Cette différence doit être connue avant une reprise. Elle évite de promettre une preuve que les données ne peuvent pas fournir.
Décrire incidents, reprises et gestes de run
Les sachants connaissent souvent les gestes qui maintiennent l’application vivante : relancer un traitement, corriger un doublon, débloquer une file, ignorer un faux positif, contrôler un export ou prévenir une équipe avant une clôture.
Ces gestes doivent être documentés avec leur contexte, leur fréquence, leur risque et leur limite. Sinon, le nouveau repreneur les découvrira dans l’urgence.
Un runbook doit expliquer le pourquoi
Une procédure qui décrit seulement les clics ou les commandes reste fragile. Il faut expliquer le symptôme, la cause probable, les vérifications préalables, l’action autorisée, le résultat attendu et les signes d’échec.
Ce niveau de précision permet de reprendre sans transformer chaque incident en enquête.
Les reprises manuelles doivent être encadrées
Une reprise manuelle n’est pas toujours mauvaise. Elle peut être nécessaire pour corriger un cas rare. Mais elle doit laisser une trace, avoir un propriétaire et être reliée à un risque connu.
Si une reprise revient souvent, elle devient un signal de dette à traiter dans la trajectoire de refonte.
Relier code, flux et dépendances
La documentation technique doit aider à naviguer. Elle n’a pas besoin de recopier tout le code. Elle doit montrer les modules sensibles, les dépendances externes, les traitements planifiés, les points d’entrée, les flux de données et les zones dangereuses.
Cette carte devient précieuse pour une refonte logiciel métier, car elle indique où isoler, tester, remplacer ou conserver temporairement.
Les flux sortants sont souvent les plus oubliés
Les équipes documentent volontiers ce qui entre dans le système, mais moins ce qui en sort : exports, emails, API partenaires, fichiers, notifications, rapports et synchronisations.
Pourtant, ces flux portent souvent des obligations métiers. Les oublier dans la documentation crée des régressions lors de la migration.
Les dépendances doivent avoir un niveau de criticité
Toutes les dépendances ne méritent pas le même traitement. Une API critique de paiement, un export de clôture ou un référentiel client doivent être distingués d’une dépendance de confort.
Ce niveau de criticité aide à prioriser les tests, la supervision et les premiers lots de reprise.
Choisir un format utile aux équipes
Une documentation legacy échoue souvent parce qu’elle devient trop longue, trop abstraite ou trop vite obsolète. Le bon format doit être consultable pendant une reprise, une recette, un incident ou un atelier de migration.
Une fiche courte par zone sensible fonctionne souvent mieux qu’un document unique. Elle peut contenir la finalité métier, les règles clés, les données manipulées, les flux, les incidents connus, les gestes de reprise et les points d’attention.
La documentation doit être liée aux décisions
Chaque fiche doit aider à décider : peut-on modifier cette zone, migrer cette donnée, remplacer ce traitement, fermer cet écran ou former une nouvelle personne ?
Si une note ne sert à aucune décision, elle risque de ne jamais être relue.
Un format vivant vaut mieux qu’un document parfait
La documentation doit pouvoir être corrigée après chaque incident, atelier, recette ou lot de migration. Elle gagne en valeur quand elle accompagne le projet, pas quand elle fige une photo trop ancienne.
L’équipe doit donc prévoir un propriétaire, une date de revue et un lien vers les zones de code ou de backlog concernées.
Organiser la transmission avant le départ
La transmission ne se limite pas à demander une documentation écrite. Il faut organiser des sessions guidées avec les sachants, les faire commenter des cas réels et vérifier que d’autres personnes peuvent rejouer le raisonnement.
Le meilleur test consiste à confier un scénario à une personne moins expérimentée : comprendre un incident, suivre un dossier, expliquer un statut, vérifier une donnée ou préparer une bascule. Si elle bloque, la documentation manque encore d’un élément essentiel.
Faire relire par ceux qui reprendront
Une documentation validée uniquement par le sachant peut rester trop implicite. Les repreneurs doivent poser les questions naïves, relever les trous et demander des exemples.
Cette confrontation améliore la qualité de transmission. Elle réduit aussi la dépendance psychologique à la personne qui part.
Conserver des exemples réels
Les exemples rendent la documentation beaucoup plus utile : dossier corrigé, incident typique, statut ambigu, export sensible, cas limite, ancien bug ou règle héritée.
Un exemple bien anonymisé vaut souvent mieux qu’une définition générale, parce qu’il montre le raisonnement attendu.
Guides complémentaires pour reprendre le legacy
Ces guides aident à transformer la documentation en trajectoire de reprise, de migration et de réduction de dette.
Décider si le legacy doit évoluer ou être repris
Le guide Legacy : refaire ou faire évoluer sans fantasme aide à replacer le savoir capturé dans une décision de trajectoire.
Découper la migration par lots réalistes
Le guide Migration : domaine, fonctionnalité ou utilisateur ? complète la documentation avec une méthode de découpage.
Comprendre la dette à traiter en priorité
Le guide Dette technique ou fonctionnelle : traiter quoi d’abord ? aide à distinguer savoir utile, dette assumée et dette bloquante.
Organiser la cohabitation pendant la reprise
Le guide Cohabitation ancien/nouveau système : réussir l’entre-deux aide à gérer la période où l’ancien et le nouveau restent actifs.
Conclusion : transformer le savoir fragile en actif projet
Documenter un legacy avant le départ des sachants n’est pas une formalité. C’est une action de maîtrise. Elle réduit la dépendance à quelques personnes, protège les données, accélère les diagnostics et évite de reconstruire une refonte sur des hypothèses.
La documentation utile capture les raisons : pourquoi cette règle existe, pourquoi cette donnée est fragile, pourquoi cette reprise est autorisée, pourquoi ce flux est critique et pourquoi telle zone ne doit pas être modifiée sans contrôle.
Le bon niveau de documentation n’est pas celui qui décrit tout. C’est celui qui permet à une nouvelle équipe de reprendre, corriger, tester, migrer et décider sans dépendre d’une mémoire orale.
Dawap accompagne les audits et reprises de legacy avec une approche croisée : audit technique application web, capture des règles métier, cartographie des données, analyse des flux, runbook, trajectoire de migration application legacy vers Symfony et priorisation de la refonte.
