Com escriure RFCs tècnics que es llegeixin de debò i portin a decisions
Les decisions tècniques més cares d'una organització d'enginyeria es prenen en fils de Slack que desapareixen, en reunions on falta la meitat dels implicats, o dins del cap d'un enginyer sènior sense el parer de ningú més. Sis mesos després, quan l'arquitectura comença a grinyolar i algú pregunta «per què ho vam construir així?», no se'n recorda ningú. O pitjor: cadascú ho recorda d'una manera diferent.
Els RFCs — els documents de Request for Comments — resolen aquest problema. Són una de les eines més potents que té un equip d'enginyeria, i una de les més infrautilitzades. He vist com transformaven la manera com un equip pren decisions, s'alinea entre zones horàries i construeix memòria institucional. I també n'he vist de mal fets: novel·les de 40 pàgines que no llegeix ningú i que ho alenteixen tot.
Vet aquí com fer-los bé.
Per què importen els RFCs
Un RFC és una proposta escrita per a una decisió tècnica significativa, que es comparteix amb l'equip per recollir-ne comentaris abans de començar a implementar. Res més. No és una especificació. No és documentació. És una proposta que demana opinions.
El valor ve de tres coses:
Claredat de pensament forçada. Escriure t'obliga a estructurar el raonament. La idea vaga que al teu cap semblava brillant es posa a prova quan l'has d'explicar per escrit. He escrit RFCs en què el simple fet d'escriure'ls em va fer veure que la solució que proposava tenia un defecte de base que m'havia passat per alt. I aquesta és justament la gràcia: surt molt més barat trobar el defecte en un document que en codi de producció.
Alineació asíncrona. En un equip distribuït que abasta diverses zones horàries, les reunions síncrones són cares i excloents. Sempre hi ha algú que s'hi connecta a deshora, sempre hi ha algú que hi falta. Un RFC permet que cadascú hi aporti la seva perspectiva quan li va bé. L'enginyer de Buenos Aires i el de Berlín llegeixen el mateix document i hi deixen els seus comentaris sense haver de quadrar mitja hora en comú a l'agenda.
Memòria institucional. D'aquí a sis mesos, algú nou a l'equip preguntarà per què el sistema fa servir event sourcing en lloc d'un CRUD tradicional. En comptes de dependre de la tradició oral («em sembla que ho va decidir la Maria, però va marxar al març»), li passes l'enllaç a l'RFC-047. El context, les alternatives i el raonament hi són tots. Només per això ja val la pena el cost d'escriure RFCs.
L'estructura d'RFC que funciona
He anat iterant plantilles d'RFC en diversos equips i organitzacions. Aquesta és l'estructura que produeix documents útils de manera consistent sense fer-se feixuga:
1. Títol i metadades
- Número i títol de l'RFC. La numeració seqüencial (RFC-001, RFC-002) facilita les referències.
- Autor(s) i data.
- Estat. Esborrany, en revisió, acceptat, rebutjat, substituït.
- Revisors. Posa-hi nom i cognoms: les persones de qui necessites específicament l'opinió.
2. Context i plantejament del problema (1-2 paràgrafs)
Quina és la situació? Quin problema volem resoldre? Per què ara? Aquesta secció situa el lector. No donis per fet que té el mateix context que tu. Enllaça-hi els tiquets, les mètriques o els incidents que facin tangible el problema.
Malament: «Hem de millorar el nostre pipeline de dades.» Bé: «El pipeline ETL per lots actual processa 2M de registres cada nit. Amb la trajectòria de creixement que portem, arribarem als 10M de registres el primer trimestre de 2024. L'arquitectura actual triga 4 hores a processar 2M de registres i no escalarà linealment. El mes passat vam tenir dos incidents en què el job nocturn no va acabar abans de l'horari laboral (INC-234, INC-251).»
3. Solució proposada (el cor del document)
Descriu què vols construir, com funciona i per què aquest enfocament i no un altre. Inclou-hi:
- Arquitectura o disseny del sistema. Els diagrames ajuden. Un diagrama senzill de caixes i fletxes comunica més que cinc paràgrafs de text.
- Les decisions tècniques clau de la proposta i per què les has pres.
- Abast. Què hi entra i, sobretot, què en queda explícitament fora.
4. Alternatives considerades (secció innegociable)
Llista com a mínim dues alternatives que hagis avaluat i per què les has descartat. Aquesta secció fa tres coses: demostra que has fet els deures, s'avança als comentaris del tipus «i per què no has considerat X?», i documenta el mapa de la decisió per als lectors futurs.
Si no se t'acut cap alternativa, és que encara no has pensat prou en el problema.
5. Riscos i preguntes obertes
Què pot sortir malament? De què no estàs segur? Quines suposicions fas que podrien ser falses? Aquesta secció és on viu l'honestedat intel·lectual. Una proposta que afirma que no té cap risc no és una proposta segura: és una proposta ingènua.
6. Pla d'implementació
Un calendari orientatiu i les fases. No cal un pla de projecte detallat — només prou detall per veure que és factible i per identificar dependències. «Fase 1: migrar la capa d'ingesta (2 setmanes). Fase 2: migrar la capa de transformació (3 setmanes). Fase 3: retirar el pipeline antic (1 setmana).»
7. Decisió i resultat (s'omple després de la revisió)
Què s'ha decidit? Quan? Qui ho ha decidit? Hi ha hagut canvis respecte de la proposta original? Això tanca el cercle i converteix l'RFC de proposta en registre.
Errors comuns que maten els RFCs
Massa llarg. Si l'RFC passa de 4 pàgines, la majoria de la gent no se'l llegirà amb atenció. Hi faran una ullada en diagonal, es perdran els matisos, i o bé el validaran sense mirar-se'l o bé hi posaran objeccions que el text ja responia. Retalla sense pietat. Els detalls d'implementació, els esquemes d'API i els models de dades, als apèndixs.
Massa abstracte. «Hauríem d'adoptar una arquitectura de microserveis», sense dir quins serveis, on són les fronteres ni com es comuniquen, no és una proposta: és un desig. Un RFC ha de ser prou concret perquè algú pugui estar en desacord amb un punt específic.
Sense punt de decisió clar. L'RFC ha de dir-ho explícitament: «Necessitem una decisió abans del [data]. Si fins llavors ningú no hi posa objeccions, tirem endavant amb l'enfocament proposat.» Sense una data límit, els RFCs esdevenen esborranys perpetus que no es tradueixen mai en acció.
Escriure un RFC per a tot. No totes les decisions necessiten un RFC. Triar entre dos paquets d'NPM per formatar dates no necessita cap document. Els RFCs són per a decisions difícils de revertir, que afecten més d'un equip o que impliquen una inversió important. Jo faig servir aquesta regla: si la implementació costa menys d'una setmana i és fàcil de revertir, fes-ho i prou. Si costa més d'una setmana o és difícil de revertir, escriu un RFC.
Fer servir els RFCs per demanar permís. El procés d'RFC ha de servir per recollir opinions, no per aconseguir aprovacions. Si cada RFC ha de ser «aprovat» per un comitè, has muntat un comitè de control de canvis amb passos de més. L'objectiu són decisions millors gràcies a l'aportació col·lectiva, no un peatge burocràtic.
Com crear l'hàbit dels RFCs sense burocràcia
El repte més gros no és escriure un RFC: és convertir-ho en un hàbit d'equip. Això és el que funciona:
Comença amb una plantilla lleugera. No creïs una plantilla de 15 camps el primer dia. Comença amb Problema, Proposta, Alternatives i Riscos. Quatre seccions. Ja hi afegiràs estructura més endavant, a mesura que l'equip vegi què li és útil.
Fes que els primers RFCs siguin victòries visibles. Tria una decisió que fa temps que l'equip rumia sense decidir-se. Escriu-la en forma d'RFC. Quan en surti una decisió clara amb el raonament documentat, l'equip en veurà el valor. Això ven la pràctica millor que qualsevol mandat de procés.
Guarda els RFCs allà on la gent ja treballa. Una carpeta compartida de Google Drive que no visita ningú és on els RFCs van a morir. Posa'ls al repositori (un directori /rfcs), a Notion si és la casa del teu equip, o a Confluence si és el que et toca. Allà on l'equip ja va a buscar la informació.
Assigna revisors explícitament. Un «si us plau, reviseu-ho» adreçat a tothom no s'adreça a ningú. Posa nom a 2-3 revisors amb l'expertesa rellevant. Dona'ls una data límit. Insisteix si no responen.
Mantén el període de revisió curt. Cinc dies hàbils són més que suficients per a la majoria d'RFCs. Si un RFC es passa tres setmanes en revisió, l'autor ja n'ha desconnectat mentalment i el document queda desfasat.
Celebra els bons RFCs. Quan algú escriu un RFC que estalvia una mala decisió a l'equip o que porta a una arquitectura clarament millor, digues-ho en veu alta. «L'RFC de l'Alejandro sobre l'estratègia de memòria cau ens va salvar d'un disseny que hauria petat amb 10 vegades la càrrega» fa que escriure RFCs es percebi com una cosa valuosa, no com uns deures.
Els equips distribuïts són els qui més necessiten els RFCs
Els RFCs encara guanyen més valor quan l'equip és distribuït. Són el gran anivellador: l'enginyer que parla menys a les reunions té exactament la mateixa veu en un document escrit. El company d'una altra zona horària no es perd la discussió, perquè no hi ha cap discussió a perdre's. Tothom hi contribueix de manera asíncrona.
A Conectia hem vist com la pràctica dels RFCs marca una diferència tangible en el funcionament dels equips distribuïts. Quan els nostres enginyers sèniors s'incorporen a l'equip d'un client, un procés d'RFC clar els permet aportar criteri arquitectònic des del primer dia, no només codi. Entenen el context de les decisions ja preses (perquè està escrit) i poden proposar millores pel mateix canal estructurat. Així és com els equips distribuïts prenen decisions tan bé com els presencials — o millor.
La inversió és petita: una plantilla, un lloc on guardar-los i el compromís d'escriure abans de construir quan la decisió és important. El retorn és enorme: decisions millors, menys converses del tipus «i això per què ho vam fer?», i un equip que pensa abans de programar.
Estàs construint un equip distribuït que prengui decisions tècniques sòlides de manera asíncrona? Parla amb un CTO — els nostres enginyers sèniors de LATAM aporten el pensament estructurat i les habilitats de comunicació que els equips distribuïts necessiten.
