Scrivere RFC Tecnici che Vengano Davvero Letti e Guidino le Decisioni
Le decisioni tecniche più costose in un'organizzazione d'ingegneria avvengono in thread di Slack che scompaiono, in riunioni dove metà degli stakeholder è assente, o nella testa di un ingegnere senior senza l'apporto di nessun altro. Poi sei mesi dopo, quando l'architettura scricchiola e qualcuno chiede "perché l'abbiamo costruito così?", nessuno ricorda. O peggio, tutti ricordano in modo diverso.
Gli RFC — documenti di Richiesta di Commenti — risolvono questo problema. Sono uno degli strumenti più potenti disponibili per i team d'ingegneria, e uno dei più sottoutilizzati. Li ho visti trasformare il modo in cui i team prendono decisioni, si allineano tra fusi orari e costruiscono memoria istituzionale. Li ho anche visti fatti male, diventando romanzi di 40 pagine che nessuno legge e che rallentano tutto.
Ecco come farli bene.
Perché gli RFC Sono Importanti
Un RFC è una proposta scritta per una decisione tecnica significativa, condivisa con il team per ottenere feedback prima che inizi l'implementazione. Tutto qui. Non una specifica. Non documentazione. Una proposta che invita contributi.
Il valore deriva da tre cose:
Chiarezza di pensiero forzata. Scrivere ti costringe a strutturare il tuo ragionamento. L'idea vaga che sembrava ottima nella tua testa viene testata quando devi spiegarla su carta. Ho scritto RFC dove l'atto di scrivere ha rivelato che la mia soluzione proposta aveva un difetto fondamentale che non avevo notato. Questo è il punto — è meno costoso trovare il difetto in un documento che nel codice di produzione.
Allineamento asincrono. In un team distribuito che si estende su più fusi orari, le riunioni sincrone sono costose ed esclusive. Qualcuno si unisce sempre a un'ora scomoda, qualcuno manca sempre. Un RFC permette a tutti di contribuire con la propria prospettiva secondo i propri tempi. L'ingegnere a Buenos Aires e quello a Berlino leggono lo stesso documento e aggiungono i loro commenti senza dover trovare una sovrapposizione di 30 minuti.
Memoria istituzionale. Tra sei mesi, un nuovo membro del team chiederà perché il sistema usa l'event sourcing invece di un pattern CRUD tradizionale. Invece di affidarsi alla storia orale ("credo che Maria abbia deciso quello, ma è andata via a marzo"), li indichi all'RFC-047. Il contesto, le alternative e il ragionamento sono tutti lì. Questo da solo vale il costo di scrivere RFC.
La Struttura RFC che Funziona
Ho iterato sui template RFC in più team e organizzazioni. Questa è la struttura che produce costantemente documenti utili senza essere gravosa:
1. Titolo e metadati
- Numero RFC e titolo. La numerazione sequenziale (RFC-001, RFC-002) facilita i riferimenti.
- Autore/i e data.
- Stato. Bozza, In Revisione, Accettato, Rifiutato, Sostituito.
- Revisori. Nomina le persone di cui hai specificamente bisogno di input.
2. Contesto e dichiarazione del problema (1-2 paragrafi)
Qual è la situazione? Quale problema stiamo risolvendo? Perché adesso? Questa sezione ancora il lettore. Non assumere che abbiano lo stesso contesto che hai tu. Collega ai ticket, metriche o incidenti rilevanti che rendono il problema concreto.
Male: "Dobbiamo migliorare la nostra pipeline dati." Bene: "La nostra pipeline ETL batch attuale elabora 2M di record ogni notte. Con la nostra traiettoria di crescita, raggiungeremo 10M di record entro il T1 2024. L'architettura attuale impiega 4 ore per elaborare 2M di record e non scalerà in modo lineare. Il mese scorso abbiamo avuto due incidenti in cui il job batch non si è completato prima dell'orario lavorativo (INC-234, INC-251)."
3. Soluzione proposta (il nucleo del documento)
Descrivi cosa vuoi costruire, come funziona e perché questo approccio. Includi:
- Architettura o design del sistema. I diagrammi aiutano. Un semplice diagramma di box e frecce comunica più di cinque paragrafi di testo.
- Decisioni tecniche chiave all'interno della proposta e perché le hai prese.
- Scope. Cosa è incluso e, in modo critico, cosa è esplicitamente non incluso.
4. Alternative considerate (sezione non negoziabile)
Elenca almeno due alternative che hai valutato e perché le hai rifiutate. Questa sezione fa tre cose: mostra che hai fatto i compiti, previene i commenti "ma perché non hai considerato X?" e documenta il panorama decisionale per i futuri lettori.
Se non riesci a pensare alle alternative, non hai pensato abbastanza al problema.
5. Rischi e domande aperte
Cosa potrebbe andare storto? Su cosa sei incerto? Quali ipotesi stai facendo che potrebbero essere sbagliate? Questa sezione è dove vive l'onestà intellettuale. Una proposta che afferma zero rischi non è fiduciosa — è ingenua.
6. Piano di implementazione
Una timeline approssimativa e le fasi. Non un piano di progetto dettagliato — solo abbastanza per mostrare che è fattibile e identificare le dipendenze. "Fase 1: migrare il layer di ingestione (2 settimane). Fase 2: migrare il layer di trasformazione (3 settimane). Fase 3: dismettere la vecchia pipeline (1 settimana)."
7. Decisione ed esito (compilato dopo la revisione)
Cosa è stato deciso? Quando? Da chi? Eventuali modifiche alla proposta originale? Questo chiude il cerchio e trasforma l'RFC da proposta a record.
Errori Comuni che Uccidono gli RFC
Troppo lungo. Se il tuo RFC è oltre 4 pagine, la maggior parte delle persone non lo leggerà attentamente. Lo sfoglieranno, perderanno le sfumature e o lo approveranno senza riflettere o solleveranno obiezioni già affrontate nel testo. Sii spietato nel tagliare. Sposta i dettagli di implementazione, gli schemi API e i modelli di dati in appendici.
Troppo astratto. "Dovremmo adottare un'architettura a microservizi" senza specificare quali servizi, quali sono i confini o come comunicano non è una proposta — è un desiderio. Gli RFC devono essere abbastanza concreti da permettere a qualcuno di essere in disaccordo con un aspetto specifico.
Nessun punto di decisione chiaro. L'RFC dovrebbe dichiarare esplicitamente: "Abbiamo bisogno di una decisione su questo entro [data]. Se non vengono sollevate obiezioni entro allora, procediamo con l'approccio proposto." Senza una scadenza, gli RFC diventano bozze perpetue che non si convertono mai in azione.
Scrivere RFC per tutto. Non ogni decisione ha bisogno di un RFC. Scegliere tra due pacchetti NPM per la formattazione delle date non necessita di un documento. Gli RFC sono per decisioni difficili da invertire, che influenzano più team o che implicano un investimento significativo. Uso questa regola: se l'implementazione richiede meno di una settimana ed è facilmente reversibile, fallo e basta. Se richiede più di una settimana o è difficile da invertire, scrivi un RFC.
Usare gli RFC come permessi. Il processo RFC dovrebbe riguardare l'ottenimento di contributi, non approvazioni. Se ogni RFC deve essere "approvato" da un comitato, hai costruito un change review board con passaggi extra. L'obiettivo è decisioni migliori attraverso contributi collettivi, non burocrazia dell'approvazione.
Sviluppare l'Abitudine RFC Senza Burocrazia
La sfida più grande non è scrivere un RFC — è renderlo un'abitudine del team. Ecco cosa funziona:
Inizia con un template leggero. Non creare un template a 15 campi il primo giorno. Inizia con Problema, Proposta, Alternative, Rischi. Quattro sezioni. Puoi aggiungere struttura in seguito quando il team vede cosa è utile.
Fai sì che i primi RFC siano vittorie visibili. Scegli una decisione su cui il team è andato avanti e indietro. Scrivila come un RFC. Quando porta a una decisione chiara con ragionamento documentato, il team vede il valore. Questo vende la pratica meglio di qualsiasi mandato di processo.
Archivia gli RFC dove le persone già lavorano. Una cartella Google Drive condivisa che nessuno visita è dove gli RFC vanno a morire. Mettili nel tuo repository (una directory /rfcs), in Notion se è la casa del tuo team, o in Confluence se ci sei bloccato. Ovunque il team già cerchi informazioni.
Assegna i revisori esplicitamente. "Per favore rivedi" indirizzato a nessuno è indirizzato a nessuno. Nomina 2-3 revisori specifici la cui expertise è rilevante. Dagli una scadenza. Fai follow-up se non rispondono.
Mantieni breve il periodo di revisione. Cinque giorni lavorativi sono sufficienti per la maggior parte degli RFC. Se un RFC è in revisione per tre settimane, l'autore è già andato avanti mentalmente e il documento diventa obsoleto.
Celebra i buoni RFC. Quando qualcuno scrive un RFC che salva il team da una cattiva decisione o porta a un'architettura notevolmente migliore, evidenzialo. "L'RFC di Alejandro sulla strategia di caching ci ha salvati da un design che si sarebbe rotto con 10x di carico" fa sentire la scrittura di RFC preziosa, non come compiti.
RFC per Team Distribuiti
Gli RFC diventano ancora più preziosi quando il tuo team è distribuito. Sono il grande equalizzatore — l'ingegnere che è più silenzioso nelle riunioni ha voce uguale in un documento scritto. Il membro del team in un fuso orario diverso non perde la discussione perché non c'è nessuna discussione da perdere. Tutti contribuiscono in modo asincrono.
In Conectia, abbiamo visto la pratica RFC fare una differenza tangibile nel modo in cui operano i team distribuiti. Quando i nostri ingegneri senior si uniscono al team di un cliente, avere un processo RFC chiaro significa che possono contribuire al pensiero architetturale fin dal primo giorno, non solo codice. Capiscono il contesto dietro le decisioni esistenti (perché è scritto) e possono proporre miglioramenti attraverso lo stesso processo strutturato. È così che i team distribuiti prendono decisioni bene quanto — o meglio di — quelli co-localizzati.
L'investimento è piccolo: un template, una posizione di archiviazione e un impegno a scrivere prima di costruire per le decisioni significative. Il ritorno è enorme: decisioni migliori, meno conversazioni "perché l'abbiamo fatto così?" e un team che pensa prima di scrivere codice.
Stai costruendo un team distribuito che prende solide decisioni tecniche in modo asincrono? Parla con un CTO — i nostri ingegneri senior LATAM portano il pensiero strutturato e le competenze comunicative di cui i team distribuiti hanno bisogno.
