Dans la plupart des équipes que j’ai connues, personne ne conteste l’utilité de la documentation. Cela ne crée pas pour autant le temps nécessaire pour l’écrire.

Un incident de production attend une réponse. Une évolution réglementaire a une échéance. Une fonctionnalité doit entrer dans la prochaine version. La documentation, elle, n’a souvent ni client qui relance ni date ferme. La repousser est donc une décision parfaitement rationnelle sur le moment.

Le problème n’est pas un manque de conviction. C’est simplement que le travail d’aujourd’hui gagne presque toujours.

Poser la question reste plus rapide

Lorsque la personne qui connaît le sujet est disponible, lui poser la question est généralement plus rapide que chercher puis lire la bonne page. Une courte conversation suffit, et l’équipe peut avancer.

Sous pression, ce fonctionnement est efficace. Il installe aussi une habitude : la personne devient l’interface principale vers la connaissance.

Cela fonctionne jusqu’au jour où elle est en congé, change d’équipe ou quitte l’organisation. La réponse existe peut-être encore quelque part, mais le chemin le plus court a disparu.

Le travail n’a pas été supprimé

Une décision non documentée ne provoque pas forcément de problème immédiat. La fonctionnalité peut être livrée et le client satisfait.

La facture arrive plus tard, lorsqu’une autre personne doit reconstruire le raisonnement à partir du code, des tickets et de souvenirs incomplets. Une note de quinze minutes peut alors devenir plusieurs heures d’enquête.

La documentation n’est donc pas seulement du travail ajouté après la livraison. Elle détermine à quel moment la compréhension sera payée, et par qui.

Tout écrire n’est pas une solution

La partie utile de la documentation n’est pas nécessairement une description exhaustive du système. Les documents trop lourds vieillissent vite et deviennent difficiles à consulter.

Ce qui mérite surtout d’être conservé, c’est ce que le code ne permet pas de retrouver facilement :

  • pourquoi cette option a été retenue ;
  • quelles alternatives ont été écartées ;
  • sur quelle hypothèse métier repose le comportement ;
  • qui porte la décision ;
  • dans quel cas elle devrait être revue.

Ces éléments sont assez courts pour être capturés tant que le contexte est frais, et assez précieux pour éviter à quelqu’un de recommencer l’analyse plus tard.

Le bon moment compte davantage que la bonne intention

Les équipes prévoient souvent de documenter après l’implémentation. C’est précisément le moment où l’attention est déjà passée au sujet suivant.

Il est plus réaliste de rattacher la documentation aux moments où la compréhension évolue : après une décision, un atelier, une découverte en production ou avant un transfert. Le format peut rester léger.

La documentation ne gagnera probablement jamais seule face à l’urgence. Elle a besoin d’une place explicite dans le travail.

C’est pour cela que je la vois comme un travail pour demain : quelques minutes prises aujourd’hui évitent à la prochaine personne de repartir de zéro.