Qu’est-ce qui se passe si la personne qui connaît votre projet démissionne demain matin ?
Si la réponse vous noue le ventre, alors la reprise n’est pas finie, même si le code tourne. Le savoir concentré dans une seule tête est exactement ce qui a mis le projet en péril la première fois. Le reconstituer dans la vôtre ne règle rien, vous ne faites que déplacer la bombe d’un cran. La sortir de toute tête, voilà le vrai travail. Quatre pages, pas une de plus.
Faire remarcher un projet ne suffit pas : il faut qu’il survive au prochain départ. Trois ou quatre pages bien ciblées (comment déployer, comment c’est branché, ce qui pique) couvrent le strict nécessaire. Mieux vaut une demi-page juste qu’un manuel périmé que personne n’ouvre.
1. Refuser les deux extrêmes. Ne rien écrire reproduit le problème tel quel : la prochaine personne qui s’en va emporte la moitié du système. Tout documenter dans le détail est plus sournois. L’effort est colossal et la prose se périme dès que le code bouge. Vous voilà avec un manuel décrivant un logiciel disparu. J’ai vu une équipe entretenir un wiki de quarante pages sur une API modifiée deux fois entre-temps ; plus personne n’osait s’y fier, et le supprimer faisait peur. La cible se trouve ailleurs : ce qui compte vraiment, à la fois critique et stable. Indispensable au fonctionnement, et qui ne change pas à chaque commit.
2. Écrire la procédure de déploiement. Comment vous mettez en production, étape par étape, avec les accès et les vérifications. C’est ce dont vous avez besoin à 23 h un soir d’incident, et c’est presque toujours ce qui manque le plus. Une demi-page suffit souvent. Sur un projet repris l’an dernier, le déploiement tenait dans la tête d’un prestataire injoignable : trois commandes dans un ordre précis, plus une variable d’environnement que personne n’avait notée. Une heure à reconstituer, dix minutes à écrire.
3. Dessiner l’architecture. Les composants et leurs liens. Qui parle à quoi, où vit la base, quels services externes interviennent. Un croquis fait à la main et photographié bat trois pages de prose. Aucune lecture de code ne vous donnera cette carte d’ensemble aussi vite, parce que le code montre les pièces une à une, jamais le plan du bâtiment.
4. Consigner les pièges et les dépendances cachées. Tout ce qui surprend. « Lancer le worker avant l’API. » « Ce cron tourne à 3 h, le couper fait décrocher la facturation. » « Ce service externe doit répondre au démarrage, sinon plantage silencieux. » Voilà les savoirs tacites, ceux qu’on garde en tête sans les noter. Tant qu’ils ne sont écrits nulle part, ils repartent avec les gens et se redécouvrent en production, au mauvais moment.
5. Laisser le code porter le reste. Pour le détail du fonctionnement, ne pariez pas sur la prose. Un test qui décrit le comportement attendu est une doc qui reste vraie : elle échoue dès qu’on la contredit. C’est aussi pourquoi les tests de caractérisation posés pendant la reprise comptent double. Ils sécurisent vos modifications et ils racontent ce que le système fait réellement.
Quand vous aurez fini, relisez votre procédure de déploiement à voix haute en l’exécutant ligne à ligne sur un environnement neuf. La variable oubliée, vous la trouverez là.