Dodici controlli per capire se un documento tecnico descrive qualcosa che esiste

Ci sono documenti tecnici di quaranta pagine che si leggono in venti minuti e non lasciano niente, e documenti di nove pagine che richiedono tre letture. La differenza non sta nella lunghezza né nel numero di formule: sta in quante affermazioni si possono verificare senza chiedere niente a nessuno.

Un documento tecnico serve a permettere a un lettore competente di ricostruire il sistema descritto e di trovarne i difetti. Se dopo la lettura non si sa chi è l’avversario contro cui il sistema si difende, che cosa succede quando le ipotesi cadono e che cosa costa far funzionare la cosa, il documento non ha fatto il suo lavoro.

Quella che segue è una griglia di dodici controlli, ciascuno con un criterio di superamento verificabile. Non misura la validità di un’iniziativa né la sua convenienza: misura soltanto se il documento descrive un sistema che esiste e che è stato pensato fino in fondo.

Che cosa cerca questa griglia

• Verificabilità, non ambizione. Conta quante affermazioni si possono controllare da soli, non quanto è grande l’obiettivo dichiarato.
• Ipotesi esplicite. Un sistema distribuito si regge su ipotesi; un documento serio le scrive, uno compilativo le tace.
• Numeri con le condizioni. Una prestazione senza le condizioni in cui è stata misurata non è un numero, è un aggettivo.
• Codice corrispondente. Il repository pubblico deve contenere quello che il documento descrive, non un sito vetrina.
• Tempo di applicazione. La griglia completa richiede circa due ore per documento, la prima metà ne richiede venti minuti e scarta quasi tutto.

Perché un documento tecnico si valuta come un progetto di ingegneria

Un protocollo distribuito è una macchina che deve funzionare mentre una parte dei suoi componenti si comporta male. Questa è la sua unica differenza rispetto a un programma ordinario, ed è la ragione per cui la parte interessante del documento non è quello che il sistema fa quando tutto va bene.

Da qui discende il criterio generale. Un buon documento passa la maggior parte delle pagine a descrivere condizioni avverse: partizioni della rete, partecipanti che mentono, messaggi che arrivano in ritardo o non arrivano. Un documento debole descrive il percorso ideale in dettaglio e liquida gli altri con una frase.

Il secondo criterio riguarda l’onestà sui limiti. Ogni scelta di progetto ha un costo, e un autore che conosce il proprio sistema sa dire che cosa ha sacrificato per ottenere quello che dichiara. Un documento in cui non si sacrifica nulla descrive un sistema che nessuno ha costruito.

Esiste un terzo criterio, meno evidente e altrettanto utile: la presenza di quantità al posto degli aggettivi. Rapido, sicuro, scalabile ed efficiente sono parole che non si possono contestare, quindi non aggiungono niente. Un ritardo espresso in secondi, una soglia espressa in frazione dei partecipanti e uno spazio di archiviazione espresso in unità di misura si possono invece confrontare, e chiunque può accorgersi se il conto non regge.

Applicare la griglia non richiede di credere o non credere a nulla. Richiede di trattare il documento come una descrizione tecnica sottoposta a verifica, esattamente come si farebbe con la relazione di calcolo di una struttura: interessa che i numeri stiano in piedi, non che l’opera sia bella.

Come leggere un whitepaper: l’ordine dei controlli

Il modo più efficiente di leggere un whitepaper non è dall’inizio. Si comincia dalla sezione sul modello di sicurezza e dalla bibliografia, che insieme occupano poche pagine e dicono quasi tutto sulla serietà del resto. Poi si passa ai numeri, poi al codice, e soltanto alla fine all’introduzione.

L’introduzione va letta per ultima perché è la parte scritta per convincere, non per descrivere, ed è anche l’unica che quasi sempre è stata riscritta più volte. Leggerla per prima orienta il giudizio prima che esistano elementi per formarlo.

I dodici controlli sono raggruppati in quattro blocchi di tre. Ogni blocco si può applicare da solo, e i primi due bastano a chiudere la valutazione in senso negativo nella maggior parte dei casi. Chi ha poco tempo si ferma lì.

Conviene tenere il conto per iscritto, una riga per controllo, con esito e riferimento alla pagina. Serve a due cose: obbliga a decidere invece di lasciare impressioni sospese, e permette di rileggere il proprio giudizio a distanza di mesi, quando il documento sarà stato aggiornato e sarà utile sapere che cosa mancava nella versione precedente.

Blocco uno: le fondamenta del documento

Controllo uno. Il problema è enunciato prima della soluzione. Le prime pagine devono descrivere un problema in termini che si possono misurare: una latenza, un costo, un limite di scala, un’assunzione di fiducia da rimuovere. Se il problema è enunciato come mancanza del sistema proposto, la circolarità è già la risposta.

Controllo due. Esiste un confronto con lo stato attuale. Un sistema nuovo si giustifica rispetto a come si fa oggi la stessa cosa, e il confronto va fatto sulle stesse grandezze. Un documento che non nomina mai le soluzioni esistenti non ha superato la fase di studio.

Controllo tre. I riferimenti esistono e sono precisi. Le citazioni devono rimandare a lavori identificabili, con autori, titolo, sede e anno, e devono essere pertinenti al punto in cui compaiono. Verificarne tre a campione richiede cinque minuti: la maggior parte della letteratura crittografica è consultabile dagli archivi pubblici della associazione internazionale per la ricerca crittografica.

Blocco due: il modello di sicurezza

Controllo quattro. Il modello di minaccia è dichiarato. Il documento deve dire chi è l’avversario, che cosa controlla e che cosa non controlla: quale frazione dei partecipanti, quale porzione della rete, quale capacità di calcolo, quale visibilità sui messaggi. Senza questa definizione, la parola sicuro non ha significato.

Controllo cinque. Le ipotesi sono esplicite. Ogni protocollo di consenso poggia su una soglia di partecipanti corretti, su un’ipotesi di sincronia della rete e su ipotesi crittografiche precise. Le tre vanno scritte, non sottintese, e vanno scritte con i numeri: una maggioranza semplice e una soglia di due terzi descrivono sistemi diversi.

Controllo sei. È descritto che cosa succede quando le ipotesi cadono. È la sezione che separa i documenti seri da tutti gli altri. Un sistema può fermarsi, può accettare stati contraddittori, può recuperare con un intervento esterno: sono esiti molto diversi e il lettore ha diritto di sapere quale lo aspetta.

Blocco tre: i numeri e le prove

Controllo sette. Ogni numero ha le sue condizioni di misura. Una capacità di elaborazione dichiarata deve indicare il numero di nodi, la loro distribuzione geografica, la banda disponibile, il tipo di operazioni misurate e la durata della prova. Un numero senza queste indicazioni non è confrontabile con nulla.

Controllo otto. Le grandezze sono coerenti fra loro. Questo controllo si fa con una moltiplicazione. Operazioni al secondo per dimensione media di ciascuna dà i dati al secondo che ogni nodo deve ricevere e conservare; se il risultato supera quello che una connessione ordinaria sostiene, il documento sta descrivendo una rete di pochi nodi molto grandi, e dovrebbe dirlo.

Controllo nove. Esiste un’analisi dei costi. Le prestazioni senza i costi raccontano metà della storia. Servono lo spazio di archiviazione richiesto per anno, la crescita dello stato, il costo di verifica per un nodo che non partecipa alla produzione e le risorse necessarie per entrare a far parte della rete.

Blocco quattro: il codice e le regole di governo

Controllo dieci. Il codice pubblico corrisponde al documento. Il repository va aperto e guardato per dieci minuti: data del primo commit, frequenza dei contributi, numero di persone diverse che hanno scritto, presenza dei test, corrispondenza fra i nomi dei moduli e le sezioni del documento. Una vetrina con un solo file di configurazione non è un’implementazione.

Controllo undici. Le regole di aggiornamento sono descritte. Chi può modificare i contratti, con quale procedura, con quale preavviso e con quale possibilità di opposizione. Nei sistemi costruiti su piattaforme programmabili questa parte pesa quanto la crittografia, e le convenzioni tecniche di riferimento sono raccolte nella collezione pubblica delle proposte di miglioramento.

Controllo dodici. La distribuzione e gli incentivi sono descritti come il protocollo. Quantità complessiva, criteri di assegnazione, calendario dei rilasci, destinatari delle quote riservate e comportamento del sistema quando le ricompense diminuiscono. Un documento tecnico impeccabile che dedica tre righe a questa parte ha lasciato fuori metà del sistema, come accade spesso nelle analisi di infrastrutture di rete recenti.

I dodici controlli con il criterio di superamento

Un documento che supera dieci controlli su dodici descrive quasi certamente qualcosa che esiste. Sotto i sette, il problema non è il progetto: è che il documento non contiene abbastanza informazione per giudicarlo, il che è già una risposta.

I segnali del documento compilativo

Esiste una categoria di testi scritti raccogliendo paragrafi da fonti diverse e cucendoli insieme. Si riconoscono da un’incoerenza di registro: sezioni molto precise accanto a sezioni generiche, con un salto di stile che nessun autore singolo produrrebbe.

Il secondo segnale è la ridondanza descrittiva. Tre pagine per spiegare che cos’è una funzione di hash e mezza pagina per il meccanismo proprietario che dovrebbe essere il contributo originale. Il rapporto fra spazio dedicato al noto e spazio dedicato al nuovo è una misura affidabile di quanto nuovo ci sia.

Il terzo è l’assenza di negativi. Nessun limite dichiarato, nessuna condizione in cui il sistema funziona peggio, nessun confronto perso. Chi ha costruito qualcosa conosce i punti in cui cede, e in genere li scrive perché è il modo in cui si chiede aiuto alla comunità tecnica.

Le tre formule che non contengono informazione

La prima è la prestazione dichiarata senza contesto: un numero di operazioni al secondo che compare in copertina e non ricompare più nel documento con le condizioni di misura. Va trattata come assente finché non si trova la sezione che la sostiene.

La seconda è l’elenco dei settori destinatari. Sanità, logistica, catena di fornitura, identità, finanza, gioco: quando compaiono tutti insieme in una pagina, quella pagina descrive un desiderio di mercato e non un’architettura. Un sistema tecnico ha vincoli che lo rendono adatto ad alcune cose e inadatto ad altre.

La terza è la sicurezza affermata come proprietà. Un sistema non è sicuro: è sicuro contro un avversario definito, sotto ipotesi dichiarate, con un margine quantificato. La differenza fra le due formulazioni distingue chi ha studiato il problema da chi lo ha descritto, ed è la stessa attenzione che serve quando si confrontano architetture di rete diverse fra loro.

Che cosa fare quando il documento supera i controlli

Superare la griglia significa una cosa sola: il documento descrive un sistema coerente, pensato e verificabile. Non dice che il sistema funzionerà su scala reale, non dice che sarà adottato e non dice nulla su nessuna valutazione economica, che dipende da fattori del tutto diversi.

Il passo successivo è confrontare il documento con quello che il sistema fa davvero, quando esiste una rete funzionante. Le grandezze dichiarate si osservano sui dati pubblici della rete stessa: numero di nodi indipendenti, distribuzione geografica, dimensione dello stato, tempi effettivi di finalizzazione. È il controllo più severo perché non dipende da nessuna dichiarazione.

Vale infine ricordare la scadenza di ogni lettura di questo tipo. Un documento descrive il progetto in una data; il codice cambia, le regole di governo cambiano, i parametri vengono modificati. Una valutazione di due anni fa va rifatta, e il modo più rapido è ripartire dai controlli dieci e undici, che sono i due che si muovono di più, come vale per tutte le trasformazioni in corso nel settore.

Domande frequenti

Serve una preparazione tecnica per applicare questa griglia?

Per otto controlli su dodici basta saper leggere con attenzione e fare una moltiplicazione. I controlli sul modello di sicurezza e sulle ipotesi richiedono qualche nozione di sistemi distribuiti, ma il criterio di superamento è la presenza di una risposta esplicita, non la sua correttezza formale.

Un documento senza formule matematiche è per forza debole?

No. Molti sistemi solidi sono descritti in prosa, e molte formule servono a decorare. Quello che conta è la presenza delle ipotesi e dei limiti: un testo in prosa che dichiara la soglia di partecipanti corretti e il comportamento fuori ipotesi vale più di venti pagine di notazione senza modello di minaccia.

Come faccio a sapere se il codice pubblico corrisponde a quello che gira davvero?

Non lo sai per certo senza una compilazione riproducibile, che è una pratica ancora poco diffusa. Un’indicazione parziale la danno la corrispondenza fra la versione pubblicata e quella dichiarata dai nodi, e l’esistenza di più implementazioni indipendenti dello stesso protocollo.

Quanto pesa l’assenza di revisioni indipendenti?

Molto, ma va letta insieme all’età del progetto. L’assenza di revisioni su un sistema recente è normale; su un sistema che gestisce valori rilevanti da anni è un dato in sé. Conta anche la loro pubblicazione integrale: una revisione citata ma non consultabile non è verificabile.

Se il documento supera dieci controlli, il progetto è affidabile?

Significa che il documento è serio, che è una condizione necessaria e non sufficiente. Un sistema ben descritto può fallire nell’esecuzione, nella distribuzione o nella gestione delle chiavi di aggiornamento. La griglia serve a scartare in fretta, non a promuovere.

La domanda utile davanti a un documento tecnico non è se convinca, ma quante delle sue affermazioni si possano controllare senza chiedere il permesso a nessuno. Nei testi che descrivono sistemi reali quella quota è alta, e si misura in un pomeriggio.