Le decisioni che non scrivi diventano debito

«Francesco, tu stai scrivendo l'architettura. Quindi la documentazione — le decisioni che prendi, i compromessi che scegli — è un deliverable. Importante quanto il codice.»

Me lo disse il mio referente nel 2016. Non l'ho più dimenticato.

L'incarico

Era il mio primo incarico da Technical Architect: progettare da zero l'architettura applicativa per un grande retailer internazionale. Single-page application per il web, più le build ibride per i dispositivi che il personale usava in negozio. Ero un consulente esterno, ero l'unico a prendere le decisioni, e intorno a me tutti venivano dal mondo Java Enterprise. Ogni scelta era sotto esame.

La decisione difficile

Presi decisioni difficili. Quella che ho difeso di più: adottare una tecnologia front-end stabile, ma avvolgerla in uno strato — scritto apposta — perché il giorno in cui fosse servita una migrazione alla versione major successiva, la strada fosse già aperta. Stessa cosa per le pipeline di build e deploy: le ho scritte a mano per ogni target, web e ibrido.

Niente di tutto ciò era la scelta ovvia dell'epoca. La scelta ovvia era qualunque cosa suggerisse il dibattito sul framework del mese. Ciò che rendeva la mia scelta difendibile non era che fosse ingegnosa: era che sapevo spiegare il perché — il compromesso esplicito tra consegnare qualcosa di stabile oggi e tenere aperta la porta per il domani.

La frase che ha cambiato tutto

Poi arrivò quella frase del mio referente. E capii cosa significasse davvero solo dopo.

A fondamenta gettate, ho dovuto spiegare e difendere ogni singola scelta davanti a stakeholder italiani e americani — persone con ruoli diversi, esperienze diverse, ciascuna interessata a un'angolazione diversa. Ho dovuto insegnare a developer e DevOps su due continenti come usare ciò che avevo costruito. Da consulente esterno, senza nessuna dell'autorità informale che viene dall'essere «uno di noi».

Senza le decisioni messe per iscritto, sarebbe stato impossibile. Non il codice — il codice era lì, leggibile da chiunque. Le decisioni. Il ragionamento dietro ognuna. Le alternative che avevo considerato e scartato, e perché.

Cosa faccio oggi: decision record leggeri

Quell'esperienza è diventata un'abitudine che porto in ogni team, ed è la prima cosa che promuovo: registrare le decisioni architetturali nel momento in cui si prendono. Non un documento di quaranta pagine che nessuno legge — un record breve e datato per ogni decisione significativa:

• il contesto e il problema;
• le opzioni sul tavolo;
• la scelta, e il compromesso esplicito che accetta;
• se è una porta a senso unico (difficile tornare indietro) o a doppio senso (economica da cambiare poi).

Il settore ha un nome per tutto questo — Architecture Decision Record (ADR) — ma il nome conta meno della disciplina. Basta un file markdown nel repository, accanto al codice.

La lezione

Ecco cosa mi hanno insegnato quindici anni:

Le decisioni che non scrivi diventano debito. Il codice dice cosa fa il sistema. Solo le decisioni scritte dicono perché — e il perché è l'unica cosa che non puoi ricostruire leggendo il codice. Sei mesi dopo, chi chiede «perché l'abbiamo fatto così?» spesso sei tu.

Qual è stata la frase, o il momento, che ha cambiato il modo in cui lavorate? Sono davvero curioso di leggere i vostri turning point.