Un visor de repositoris que vaig fer l'estiu passat té vuit commits la primera setmana. Els quatre primers no toquen ni una línia d'aplicació: són l'init des de la meva plantilla i tres commits de documentació. El cinquè ja és l'app sencera.
No va ser disciplina. Va ser que en escriure el document vaig descobrir que tenia malament el model mental de la integració, i arreglar-ho en un .md costava vint minuts en comptes de dos dies.
L'error de començar pel codi en una integració aliena
Quan la lògica és teva, llegir el codi és la millor documentació que existeix. Quan depèn d'una API aliena, no: el que necessites saber no és al teu codi ni al d'ells. És als límits, les quotes i els paràmetres obsolets.
En aquell visor vaig confondre durant una estona dues connexions amb el mateix proveïdor. L'OAuth de login i el token de servidor per llegir l'API semblen el mateix i no ho són. L'un serveix perquè hi entri un humà, l'altre perquè el servidor llegeixi. Fallen diferent. Escriure-ho en un document separat en dues seccions va ser el que em va fer veure que un visor de repos públics només necessitava el segon.
Si hagués començat pel codi, això ho hauria descobert al tercer 401.
Què documento exactament abans de la primera línia
No documento el disseny de la meva app. Documento el que no controlo. En concret:
- Els límits reals, mesurats, no citats. No n'hi ha prou de copiar "5.000 peticions per hora" del web. Ho vaig demanar a l'endpoint de quota: 60/h sense autenticar, 5.000/h autenticat, 30/min en cerca. I vaig mesurar que un
304 Not Modifiedno gasta quota — 4972, 4972, 4972 amb condicionals, i 4971 en la mateixa crida senseIf-None-Match. Aquest número repetint-se és l'argument central del document, i sense executar-ho no el tens. - El que no es pot automatitzar. L'OAuth App no es crea per CLI: no hi ha endpoint per crear-la ni per llegir el client secret, que s'ensenya una sola vegada al navegador. És un pas manual, i el dia que muntis l'entorn de nou ho hauràs oblidat.
- Els sostres que sorprenen en producció. 2.000 creacions de token per hora, que és sostre de logins, no de peticions. I reautorització forçada si un usuari hi entra deu vegades en una hora. Cap dels dos no apareix quan llegeixes el happy path.
- El que la decisió NO resol. Vaig anotar que obligar a fer login no elimina la necessitat de cau condicional, perquè el bucket de l'usuari està compartit amb el seu PAT i amb altres apps que actuïn en nom seu. Si no ho escrius, la decisió et dona una falsa seguretat.
Res d'això no és opinable. Són fets que o comproves o t'inventes.
Els cookbooks: provar cada peça aïllada abans d'integrar-la
En un servei d'IA per a anàlisi documental vaig fer el mateix d'una altra manera. Abans que cap peça entrés al servei, cadascuna tenia un cookbook: un script que l'executa sola, escriu la seva sortida a una carpeta i es registra en un run_all_cookbooks. Parser de PDF, chunker, embeddings, detector de números, extracció verificable. Un per peça.
El valor no és el test. És que quan la sortida del chunker canvia de forma, es veu en un fitxer de text en comptes d'en una fallada tres capes més amunt. En passar el pipeline a asíncron, els cookbooks es van convertir en runners amb asyncio.run i la migració es va fer peça a peça, no de cop.
El cost és que cal esborrar-los quan deixen de valer. Mesos després hi ha un commit que treu els cookbooks obsolets. Un cookbook que ja no correspon a la peça és pitjor que cap.
La documentació com a font de veritat per auditar després
En una galeria de conceptes d'UI vaig escriure primer una guia de disseny de la peça — talles, escala d'espaiat, escala de grisos, quin primitiu es fa servir per a què — i després vaig auditar el codi contra ella.
L'interessant és que l'auditoria va corregir la guia, no només el codi. Tres coses que el .md deia de menys: que el gris acompanyant es gradua en cinc esglaons i no en dos; que l'escala d'espaiat té quatre graons i no tres, perquè dir-ne de tres convertia sis usos legítims en deriva; i que els tres diàlegs són en realitat el mateix diàleg, amb la mateixa caixa i la mateixa capçalera, i en no dir-ho la correcció s'havia aplicat només a un.
Sense document previ aquestes tres troballes no existeixen. No tens contra què comparar i tot el que trobes és "a mi em sembla".
Quan això és perdre el temps
El criteri que faig servir:
- Si la integració és teva de punta a punta, no documentis abans. El codi és la veritat i el document envelleix.
- Si és un prototip que llençaràs, tampoc. Un joc que vaig escriure en un dia no té res escrit i està bé així.
- Si el document repetirà el que diu la referència oficial, no l'escriguis. Només aporta si té els teus mesuraments, les teves versions i els paranys que et van tocar a tu.
I hi ha una fallada que em va costar cara: el document escrit abans porta a dins les teves suposicions. Al visor, la secció d'allotjament descrivia una plataforma serverless perquè jo ho vaig donar per fet en redactar l'encàrrec, no perquè ningú ho hagués decidit. En corregir-ho a un contenidor de llarga vida va canviar la conclusió sencera: en serverless l'SDK d'agents no hi cabia; en un worker amb quinze minuts de límit de petició, sí.
Per això el pas següent no és opcional. Hi ha un commit la feina única del qual és verificar el document contra fonts vives: executar la consulta que apareix a la guia, enviar una versió d'API invàlida perquè la mateixa API enumeri les vàlides, comprovar que per_page=500 es retalla a 100 en silenci, tipar el snippet que no compilava en mode estricte. Aquell commit va trobar que 18 de 20 "issues" retornades eren en realitat pull requests.
Un document sense verificar és una suposició amb format bonic. Un document verificat és l'única part de la integració que no et mentirà d'aquí a sis mesos.