Écrire un compte-rendu, c'est penser deux fois
Pourquoi je rédige des compte-rendus après la livraison — et ce que l'écriture continue de révéler que le travail avait raté.
La première fois que j’ai rédigé un compte-rendu de projet correctement, j’ai trouvé un bug. Pas dans le code — le code était en production depuis des mois. Le bug était dans ma compréhension de pourquoi le projet avait fonctionné.
J’avais attribué un gain de performance à un changement alors que, en le rédigeant dans l’ordre, c’était manifestement un autre. L’histoire que je racontais aux gens était fausse. Personne ne l’avait remarqué, parce que personne n’avait été contraint de dérouler le raisonnement de bout en bout.
C’est la valeur discrète d’un compte-rendu. La revue de code vérifie si le travail est correct. L’écriture vérifie si votre compréhension du travail est correcte, et ce ne sont pas la même chose.
La structure fait le travail
Je rédige chaque projet de la même manière : problème, contexte, processus, résultat, réflexion. Cela semble rigide jusqu’à ce qu’on réalise que la structure vous interroge.
« Contexte » demande pourquoi le problème existait en premier lieu, ce qui vous permet de découvrir que vous avez traité un symptôme. « Réflexion » demande ce que vous feriez différemment, ce qui vous permet d’admettre ce que vous évitiez d’admettre. Les titres ne sont que des questions qu’un bon collègue poserait, posées de façon fiable.
Écrivez pour la version de vous dans deux ans
Le public d’un compte-rendu n’est pas vraiment d’autres personnes. C’est vous, plus tard, ayant tout oublié, essayant de vous rappeler si cette approche a fonctionné et pourquoi. Écrivez pour que cette personne vous fasse confiance. Soyez honnête sur les compromis et les parties qui ont eu de la chance.
Si l’écriture est bonne, le design disparaît derrière elle — et l’auto-congratulation aussi. Ce qui reste, c’est le raisonnement, qui est la seule partie qui mérite d’être conservée.