Escriure RFCs Tècnics que Realment es Llegeixen i Impulsen Decisions
Les decisions tècniques més cares en una organització d'enginyeria succeeixen en fils de Slack que desapareixen, en reunions on la meitat dels stakeholders estan absents, o al cap d'un enginyer sènior sense l'aportació de ningú més. Llavors sis mesos després, quan l'arquitectura cruja i algú pregunta "per què ho vam construir d'aquesta manera?", ningú ho recorda. O, pitjor, tothom ho recorda de manera diferent.
Els RFCs — documents de Request for Comments — resolen aquest problema. Són una de les eines més poderoses disponibles per als equips d'enginyeria, i una de les més infrautilitzades. He vist com transformen la manera en que els equips prenen decisions, s'alineen entre zones horàries i construeixen memòria institucional. També els he vist mal fets, convertint-se en novel·les de 40 pàgines que ningú llegeix i que tot ho alenteixen.
Aquí s'explica com fer-los bé.
Per Què Importen els RFCs
Un RFC és una proposta escrita per a una decisió tècnica significativa, compartida amb l'equip per obtenir retroalimentació abans que comenci la implementació. Això és tot. No és una especificació. No és documentació. És una proposta que convida a l'aportació.
El valor prové de tres coses:
Claredat de pensament forçada. Escriure t'obliga a estructurar el teu raonament. La idea vaga que semblava fantàstica en el teu cap es prova quan has d'explicar-la en paper. He escrit RFCs on l'acte d'escriure va revelar que la meva solució proposada tenia un defecte fonamental que no havia notat. Aquell és el punt — és més barat trobar el defecte en un document que en codi de producció.
Alineació asíncrona. En un equip distribuït que abarca múltiples zones horàries, les reunions síncrones són cares i excloents. Algú sempre s'uneix en una hora inconvenient, algú sempre falta. Un RFC permet a tothom contribuir amb la seva perspectiva en el seu propi horari. L'enginyer a Buenos Aires i el de Berlín llegeixen el mateix document i afegeixen els seus comentaris sense necessitar trobar una superposició de 30 minuts.
Memòria institucional. Sis mesos a partir d'ara, un nou membre de l'equip preguntarà per què el sistema utilitza event sourcing en lloc d'un patró CRUD tradicional. En lloc de dependre de la història oral ("crec que la Maria ho va decidir, però va marxar al març"), els assenyales al RFC-047. El context, les alternatives i el raonament estan tots allà. Això sol ja val el cost d'escriure RFCs.
L'Estructura de RFC que Funciona
He iterat en plantilles de RFC en múltiples equips i organitzacions. Aquesta és l'estructura que consistentment produeix documents útils sense ser onerosa:
1. Títol i metadades
- Número i títol de RFC. La numeració seqüencial (RFC-001, RFC-002) facilita la referència.
- Autor(s) i data.
- Estat. Esborrany, En Revisió, Acceptat, Rebutjat, Superat.
- Revisors. Nomena les persones l'aportació de les quals específicament necessites.
2. Context i declaració del problema (1-2 paràgrafs)
Quina és la situació? Quin problema estem resolent? Per què ara? Aquesta secció situa el lector. No assumeixis que tenen el mateix context que tu. Enllaça a tiquets, mètriques o incidents rellevants que facin concret el problema.
Malament: "Necessitem millorar el nostre pipeline de dades." Bé: "El nostre pipeline ETL per lots actual processa 2M de registres cada nit. Amb la nostra trajectòria de creixement, arribarem als 10M de registres el primer trimestre de 2024. L'arquitectura actual tarda 4 hores en processar 2M de registres i no escalarà linealment. El mes passat vam tenir dos incidents on la feina per lots no es va completar abans de les hores de negoci (INC-234, INC-251)."
3. Solució proposada (el nucli del document)
Descriu el que vols construir, com funciona i per què aquest enfocament. Inclou:
- Arquitectura o disseny del sistema. Els diagrames ajuden. Un diagrama simple de caixetes i fletxes comunica més que cinc paràgrafs de text.
- Decisions tècniques clau dins de la proposta i per quina raó les has pres.
- Abast. El que s'inclou i, de manera crítica, el que s'exclou explícitament.
4. Alternatives considerades (secció no negociable)
Llista almenys dues alternatives que has avaluat i per quina raó les has rebutjat. Aquesta secció fa tres coses: demostra que has fet els deures, anticipa els comentaris "però per quina raó no has considerat X?" i documenta el panorama de decisions per als futurs lectors.
Si no pots pensar en alternatives, no has pensat prou en el problema.
5. Riscos i preguntes obertes
Què podria anar malament? Sobre quina cosa ets incert? Quines suposicions estàs fent que podrien ser incorrectes? Aquesta secció és on viu l'honestedat intel·lectual. Una proposta que afirma que no hi ha riscos no és confiada — és ingènua.
6. Pla d'implementació
Una línia de temps i fases aproximades. No un pla de projecte detallat — just suficient per demostrar que és factible i per identificar les dependències. "Fase 1: migrar la capa d'ingestió (2 setmanes). Fase 2: migrar la capa de transformació (3 setmanes). Fase 3: desactivar el pipeline antic (1 setmana)."
7. Decisió i resultat (omplert després de la revisió)
Què s'ha decidit? Quan? Per qui? Alguna modificació de la proposta original? Això tanca el cercle i converteix el RFC d'una proposta en un registre.
Errors Comuns que Maten els RFCs
Massa llarg. Si el teu RFC té més de 4 pàgines, la majoria de les persones no el llegiran amb cura. Faran una ullada ràpida, es perdran la matisació, i o bé ho aprovaran de goma o bé plantejaran objeccions que ja estan abordades en el text. Sigues despietat retallant. Mou 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 especificar quins serveis, quins límits, o com es comunicarien no és una proposta — és un desig. Els RFCs han de ser prou concrets com perquè algú pugui estar en desacord amb un aspecte específic.
Sense punt de decisió clar. El RFC hauria d'indicar explícitament: "Necessitem una decisió sobre això per [data]. Si no es plantegen objeccions per llavors, procedim amb l'enfocament proposat." Sense un termini, els RFCs es converteixen en esborranys perpetuals que mai es converteixen en acció.
Escriure RFCs per a tot. No tota decisió necessita un RFC. Triar entre dos paquets NPM per al format de dates no necessita un document. Els RFCs són per a decisions que són difícils de revertir, afecten múltiples equips o impliquen una inversió significativa. Uso aquesta regla: si la implementació tarda menys d'una setmana i és fàcilment reversible, simplement fes-ho. Si tarda més d'una setmana o és difícil de revertir, escriu un RFC.
Usar els RFCs com a permisos. El procés de RFC hauria de tractar-se d'obtenir aportació, no d'obtenir aprovació. Si cada RFC necessita ser "aprovat" per un comitè, has construït un consell de revisió de canvis amb passos addicionals. L'objectiu és millors decisions a través de l'aportació col·lectiva, no una burocràcia de control d'accés.
Construint l'Hàbit del RFC Sense Burocràcia
El major desafiament no és escriure un RFC — és fer-ho un hàbit de l'equip. Aquí hi ha 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, Riscos. Quatre seccions. Pots afegir estructura més tard a mesura que l'equip vegi el que és útil.
Fes que els primers RFCs siguin victòries visibles. Tria una decisió sobre la qual l'equip ha anat i vingut. Escriu-la com a RFC. Quan porta a una decisió clara amb raonament documentat, l'equip veu el valor. Això ven la pràctica millor que qualsevol mandat de procés.
Emmagatzema els RFCs on la gent ja treballa. Una carpeta compartida de Google Drive que ningú visita és on els RFCs van a morir. Posa'ls al teu repositori (un directori /rfcs), a Notion si aquesta és la llar del teu equip, o a Confluence si hi estàs atrapat. On sigui que l'equip ja busca informació.
Assigna revisors explícitament. "Si us plau reviseu" dirigit a ningú és dirigit a ningú. Nomena 2-3 revisors específics l'experiència dels quals és rellevant. Dóna'ls un termini. Fes seguiment si no responen.
Mantén el període de revisió curt. Cinc dies hàbils és suficient per a la majoria dels RFCs. Si un RFC roman en revisió durant tres setmanes, l'autor ja ha passat pàgina mentalment i el document es queda ranci.
Celebra els bons RFCs. Quan algú escriu un RFC que estalvia a l'equip d'una mala decisió o porta a una arquitectura notablement millor, fes-ho notar. "El RFC de l'Alejandro sobre l'estratègia de memòria cau ens va salvar d'un disseny que s'hauria trencat a 10x de càrrega" fa que escriure RFCs se senti valuós, no com a deures.
RFCs per a Equips Distribuïts
Els RFCs es tornen encara més valuosos quan el teu equip és distribuït. Són el gran igualador — l'enginyer que és més silenciós en les reunions té veu igual en un document escrit. El membre de l'equip en una zona horària diferent no es perd la discussió perquè no hi ha cap discussió per perdre's. Tothom contribueix de manera asíncrona.
A Conectia, hem vist que la pràctica de RFC fa una diferència tangible en com operen els equips distribuïts. Quan els nostres enginyers sèniors s'uneixen a l'equip d'un client, tenir un procés de RFC clar significa que poden contribuir amb pensament arquitectònic des del primer dia, no només codi. Entenen el context darrere de les decisions existents (perquè està escrit) i poden proposar millores a través del mateix procés estructurat. Així és com els equips distribuïts prenen decisions tan bé com — o millor que — els co-ubicats.
La inversió és petita: una plantilla, un lloc d'emmagatzematge i un compromís d'escriure abans de construir per a les decisions significatives. El retorn és enorme: millors decisions, menys converses "per quina raó vam fer això?", i un equip que pensa abans de codificar.
Estàs construint un equip distribuït que pren 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.
