Il y a 4 ans, j'ai développé seule un projet de gestion et d'agrégation de données. Son rôle : récupérer des données depuis de nombreuses sources, les transformer, les envoyer à de nombreux clients sous des formats différents. Un projet aux règles métier très spécifiques, avec des cas d'exception qui ne ressemblent à rien d'autre.
Depuis la livraison, le projet tournait seul. Pas de bugs, pas d'interventions. Des montées de version, c'est tout. Chez ce client, tout projet terminé passe en TMA : une équipe dédiée prend le relais pour la maintenance et les évolutions. Pour celui-ci, ça avait simplement tardé - le projet tournait bien, donc ce n'était pas pressé. Trois ans plus tard, la passation a enfin eu lieu.
Pourquoi j'ai documenté à l'époque
Pas par vertu. Pas parce que c'est une bonne pratique qu'on vous enseigne.
Parce que je travaillais seule sur ce projet, et que c'était plus efficace pour échanger avec le client. C'était mon lien avec le client - on y figeait la réalité de son besoin et de ce qui avait été créé.
J'ai documenté chaque fonctionnalité : ce qu'elle fait, pourquoi elle existe, quelle règle métier elle traduit.
La passation, 4 ans plus tard
5 personnes reprennent le projet - un mix de seniors et de juniors, une équipe TMA spécialisée avec laquelle travaille le client.
La passation a duré 5 heures au total : 3 sessions d'une heure sur la partie fonctionnelle, 2 sessions de 2 heures sur la partie technique. Le projet n'est pas complexe techniquement - il respecte les standards Symfony, tourne sous Docker, ce qui simplifie considérablement son installation, et possède une très bonne couverture de tests garantissant l'état des fonctionnalités. Tout cela rend le projet techniquement transmissible. Ce que la documentation a apporté en plus, c'est le pourquoi : les règles métier, les décisions d'époque, les cas d'exception qui n'ont pas d'équivalent dans le code.
Ce qui se serait passé sans elle
J'aurais dû fouiller dans une mémoire vieille de 4 ans.
Certaines fonctionnalités ont des règles métier très spécifiques - des règles que le code applique mais n'explique pas. Le "comment" est lisible dans le code. Le "pourquoi" tel client reçoit ses données dans tel format, avec telle exception pour tel cas - ça, ça ne se lit nulle part. Ça vit dans la tête du développeur qui l'a conçu.
Sans documentation, il aurait fallu faire du reverse engineering. Reconstituer l'intention à partir du résultat. Perdre du temps à reconstruire ce que le métier voulait - et risquer de se tromper.
Ce que j'en retiens
La documentation ne sert pas à expliquer le code. Le code s'explique lui-même quand il est bien écrit.
Elle sert à conserver le "pourquoi" - les décisions métier, les contraintes d'époque, les cas tordus qui ont une raison d'être même quand cette raison n'est plus visible.
Et ce "pourquoi", personne ne peut le retrouver à votre place. Pas même vous, 4 ans plus tard. Pas même l'IA si on lui donne accès au code.
