Un visualiseur de dépôts que j'ai fait l'été dernier compte huit commits dans sa première semaine. Les quatre premiers ne touchent pas une seule ligne d'application : c'est l'init depuis mon gabarit et trois commits de documentation. Le cinquième, c'est déjà l'app entière.
Ce n'était pas de la discipline. C'est qu'en écrivant le document j'ai découvert que mon modèle mental de l'intégration était faux, et le corriger dans un .md coûtait vingt minutes au lieu de deux jours.
L'erreur de commencer par le code dans une intégration tierce
Quand la logique est la tienne, lire le code est la meilleure documentation qui existe. Quand ça dépend d'une API tierce, non : ce que tu as besoin de savoir n'est ni dans ton code ni dans le leur. C'est dans les limites, les quotas et les paramètres dépréciés.
Dans ce visualiseur, j'ai confondu un moment deux connexions au même fournisseur. L'OAuth de login et le token serveur pour lire l'API ont l'air d'être la même chose et ne le sont pas. L'un sert à faire entrer un humain, l'autre à faire lire le serveur. Ils échouent différemment. L'écrire dans un document séparé en deux sections, c'est ce qui m'a fait voir qu'un visualiseur de dépôts publics n'avait besoin que du second.
Si j'avais commencé par le code, je l'aurais découvert au troisième 401.
Ce que je documente exactement avant la première ligne
Je ne documente pas la conception de mon app. Je documente ce que je ne contrôle pas. Concrètement :
- Les limites réelles, mesurées, pas citées. Il ne suffit pas de copier « 5 000 requêtes par heure » depuis le site. Je les ai demandées à l'endpoint de quota : 60/h sans authentification, 5 000/h authentifié, 30/min en recherche. Et j'ai mesuré qu'un
304 Not Modifiedne consomme pas de quota — 4972, 4972, 4972 avec des requêtes conditionnelles, et 4971 sur le même appel sansIf-None-Match. Ce nombre qui se répète est l'argument central du document, et sans l'exécuter tu ne l'as pas. - Ce qui ne peut pas être automatisé. L'OAuth App ne se crée pas en CLI : il n'y a pas d'endpoint pour la créer ni pour lire le client secret, qui n'est montré qu'une seule fois dans le navigateur. C'est une étape manuelle, et le jour où tu remonteras l'environnement tu l'auras oubliée.
- Les plafonds qui surprennent en production. 2 000 créations de token par heure, soit un plafond de logins, pas de requêtes. Et une réautorisation forcée si un utilisateur se connecte dix fois en une heure. Aucun des deux n'apparaît quand tu lis le happy path.
- Ce que la décision NE résout PAS. J'ai noté qu'imposer le login n'élimine pas le besoin de cache conditionnel, parce que le bucket de l'utilisateur est partagé avec son PAT et avec d'autres apps agissant en son nom. Si tu ne l'écris pas, la décision te donne une fausse sécurité.
Rien de tout cela n'est discutable. Ce sont des faits que tu vérifies, ou que tu inventes.
Les cookbooks : tester chaque pièce isolément avant de l'intégrer
Dans un service d'IA pour l'analyse documentaire, j'ai fait la même chose autrement. Avant qu'aucune pièce n'entre dans le service, chacune avait son cookbook : un script qui l'exécute seule, écrit sa sortie dans un dossier et s'enregistre dans un run_all_cookbooks. Parseur de PDF, chunker, embeddings, détecteur de nombres, extraction vérifiable. Un par pièce.
La valeur, ce n'est pas le test. C'est que quand la sortie du chunker change de forme, ça se voit dans un fichier texte plutôt que dans une erreur trois couches plus haut. En passant le pipeline en asynchrone, les cookbooks sont devenus des runners avec asyncio.run et la migration s'est faite pièce par pièce, pas d'un bloc.
Le coût, c'est qu'il faut les supprimer quand ils ne valent plus rien. Des mois plus tard, il y a un commit qui retire les cookbooks dépréciés. Un cookbook qui ne correspond plus à la pièce est pire que pas de cookbook du tout.
La documentation comme source de vérité pour auditer ensuite
Dans une galerie de concepts d'UI, j'ai d'abord écrit un guide de conception du composant — tailles, échelle d'espacement, échelle de gris, quelle primitive sert à quoi — puis j'ai audité le code par rapport à lui.
Ce qui est intéressant, c'est que l'audit a corrigé le guide, pas seulement le code. Trois choses que le .md disait en trop peu : que le gris d'accompagnement se gradue sur cinq échelons et non sur deux ; que l'échelle d'espacement a quatre paliers et non trois, parce que l'appeler « à trois » transformait six usages légitimes en dérive ; et que les trois boîtes de dialogue sont en réalité la même boîte, avec la même caisse et le même en-tête, et que faute de le dire la correction n'avait été appliquée qu'à une seule.
Sans document préalable, ces trois trouvailles n'existent pas. Tu n'as rien à quoi comparer et tout ce que tu trouves relève du « moi je trouve que ».
Quand c'est une perte de temps
Le critère que j'utilise :
- Si l'intégration est la tienne de bout en bout, ne documente pas avant. Le code est la vérité et le document vieillit.
- Si c'est un prototype que tu vas jeter, non plus. Un jeu que j'ai écrit en un jour n'a rien d'écrit et c'est très bien comme ça.
- Si le document va répéter ce que dit la référence officielle, ne l'écris pas. Il n'apporte quelque chose que s'il contient tes mesures, tes versions et les pièges qui te sont tombés dessus.
Et il y a une faute qui m'a coûté cher : le document écrit avant porte tes suppositions. Dans le visualiseur, la section hébergement décrivait une plateforme serverless parce que je l'avais tenu pour acquis en rédigeant la commande, pas parce que quelqu'un l'avait décidé. En la corrigeant vers un conteneur de longue durée, toute la conclusion a changé : en serverless, le SDK d'agents ne tenait pas ; dans un worker avec quinze minutes de limite par requête, si.
C'est pour ça que l'étape suivante n'est pas facultative. Il y a un commit dont le seul travail est de vérifier le document contre des sources vivantes : exécuter la requête qui figure dans le guide, envoyer une version d'API invalide pour que l'API elle-même énumère les valides, vérifier que per_page=500 est ramené à 100 en silence, typer le snippet qui ne compilait pas en mode strict. Ce commit a découvert que 18 des 20 « issues » renvoyées étaient en réalité des pull requests.
Un document non vérifié est une supposition joliment mise en forme. Un document vérifié est la seule partie de l'intégration qui ne te mentira pas dans six mois.