Architectural Decision Record (ADR): Un Documento Fondamentale Per Il Successo Di Un Progetto

Che cos’è un Architectural Decision Record?

Per capire meglio cos’è un Architectural Decision Record, possiamo basarci su alcune definizioni fornite da importanti organizzazioni del settore IT. Secondo GitHub, “Una decisione architettonica è una scelta giustificata di progettazione del software che risponde a un requisito funzionale o non funzionale architettonicamente significativo”. Spotify, invece, definisce l’ADR come “un documento che cattura una decisione, compreso il contesto in cui è stata presa e le conseguenze dell’adozione della decisione”. Se si vuole avere un quadro completo, si possono consultare anche le definizioni di Google e AWS.

Riassumendo i punti principali di ognuna di esse, puntualizziamo che in questo documento per ADR intendiamo “un documento che descrive tutte le decisioni architetturali prese su un software, solitamente affiancate dal contesto e dall’obiettivo che ha portato a tali decisioni“.

Vantaggi di un Architectural Decision Record

Un’ADR porta diversi vantaggi alle organizzazioni che decidono di implementarlo. Questi vantaggi possono essere sperimentati sia nella scrittura che nella lettura di un ADR. Vediamo questi vantaggi.

I vantaggi di scrivere un ADR

• Aiuta a identificare il divario di conoscenza per una decisione da prendere;
• Obbliga a spiegare e motivare le decisioni che si vogliono prendere;
• Può portare a valutare opzioni che non si stavano considerando;
• Guida i team a condividere le soluzioni tecniche;
• Permette di ragionare a lungo termine e non day-by-day;
• Può essere utilizzato per informare i team di sviluppo sulle best practices e altre aree come ad esempio il team di sicurezza perché siano allineati.

I vantaggi di leggere un ADR

• Facilita il processo di onboarding;
• Toglie la necessità di avere una persona che conosca tutte le informazioni e si può consultare direttamente il documento;
• Consente di verificare se alcune scelte sono già state considerate in passato;
• Può essere utilizzato con gli stakeholders per giustificare le proprie scelte o iniziative.

Rischi di un Architectural Decision Record

Come qualsiasi altro strumento, l’ADR comporta dei vantaggi, ma introduce anche nuovi rischi. I principali rischi che si possono identificare sono che l’ADR sia incompleto o non aggiornato e che diventi troppo rigido. Scopriamo perché e come evitare questi rischi.

Se il documento non viene aggiornato regolarmente si perdono tutti i vantaggi di avere un sistema per condividere la conoscenza delle scelte architetturali prese, il documento risulterà incoerente e i team non troveranno vantaggi ad utilizzarlo. È importante fare in modo che i team consultino l’ADR per rilevare eventuali incongruenze per tempo e creare uno step per la revisione di questo documento durante le fasi progettuali, per fare in modo che non ci si dimentichi di aggiornarlo.

Per tenere traccia delle decisioni si potrebbe creare un processo di validazione delle scelte architetturali che rallenta troppo i processi di sviluppo. Per evitare questo bisogna ricordare che l’ADR è un sistema di condivisione di conoscenza, perciò l’importante non è prendere la decisione migliore a discapito del tempo, ma tracciare la scelta presa qualunque essa sia.

Quando è necessario avere un Architectural Decision Record

L’ADR può essere applicato su due livelli, non necessariamente esclusivi tra loro: High Level e/o Low Level.

Per Low Level sono considerate tutte quelle decisioni prese all’interno di un singolo servizio/repository. In questo caso l’ADR si può trovare all’interno dello stesso repository del codice. All’interno di esso dovranno essere tracciate tutte le decisioni prese durante lo sviluppo, ad esempio:

• Il perché sia stata utilizzata un certa libreria;
• Il criterio di suddivisione dei file all’interno del progetto;
• Le naming convention scelte.

Invece, per High Level intendiamo tutte le decisioni prese in un’architettura IT che integra più software, componenti o plugin tra di loro. Ad esempio:

• L’utilizzo di componenti di ready-to-use di un’azienda terza a discapito dello sviluppo interno di componenti custom;
• Le funzioni e le responsabilità di un singolo applicativo;
• Come avviene la comunicazione tra i componenti, se in modo sincrono o asincrono;
• La scelta di usare un message broker e perché.

Nell’ambito di un’ azienda dove sono coinvolti più fornitori e più sviluppatori, ognuno dei quali deve intraprendere delle scelte architetturali, l’ADR è tipicamente applicato su High Level, per governare questo complesso processo.

Esempi pratici di scelte architetturali

Le scelte architetturali possono seguire due strade diverse:

• Top-down: alcune decisioni architetturali, soprattutto quelle a riguardo dei tool e delle tecnologie utilizzabili, non possono essere prese autonomamente dai team che sviluppano sulla piattaforma e.g. l’utilizzo di un determinato Message Broker piuttosto che un altro. Questo perché alcuni fattori come la licenza, gli accordi commerciali o i costi infrastrutturali potrebbero guidare questo processo.
• Bottom-up: in altri casi invece si può presentare la necessità da parte di un team di una modifica architetturale. Alcuni esempi possono essere lo sviluppo di un plugin sulla piattaforma per l’invio di mail, o un gestore per lo storage di file. In questo caso il team potrebbe presentare una richiesta o una proposta da validare e poi implementare.

Nell’iter bottom-up è importante evidenziare che l’ADR deve avere l’unico scopo di tracciare le scelte e le proposte per condividere la conoscenza, e non per rallentare le decisioni. Di seguito due esempi per chiarire meglio il concetto: il primo illustra il processo di riutilizzo di un plugin, il secondo il processo di creazione di un nuovo.

Riutilizzo di un plugin
Un team presenta la necessità di dover inviare mail sul proprio applicativo e verifica sull’ADR se sia presente una best practice per l’invio di mail. Dall’ADR viene a conoscenza di un plugin già esistente per l’invio delle mail già creato da un altro team. Il plugin è adeguato al caso d’uso e viene utilizzato per l’applicativo da cui è scaturita la necessità.

Creazione di un plugin custom
Un altro team presenta la necessità di dover inviare mail sul proprio applicativo e controlla l’ADR. Come il precedente, anche questo team viene a conoscenza del plugin già esistente. In questo caso, però, il plugin non è adeguato al caso d’uso specifico, perché non possiede una feature fondamentale. Evolvere il plugin richiederebbe un costo eccessivo e quindi il team decide di utilizzare una soluzione custom.
Anche in questo caso il team deve aggiornare l’ADR per tracciare questa decisione e la motivazione che ha portato a questa scelta.

Come si evidenzia dall’esempio, l’ADR è molto importante sia per diffondere delle best practices che per spiegare il perché queste non siano state seguite. Nel secondo caso l’ADR diventa molto utile per due motivi. Innanzitutto per tracciare la feature mancante per cui non si è utilizzato il plugin esistente. In un secondo momento, quando questa feature viene integrata sul plugin e integrata nell’applicativo, tracciare sull’ADR che quel software sta utilizzando il plugin esistente.

Cosa inserire in un Architectural Decision Record

Quando si decide di creare un ADR, bisogna stabilire un insieme minimo di informazioni da tenere per ogni singola decisione, che può essere adeguato ai vari casi d’uso. Prendendo ad esempio il template di Michael Nygard, bisognerebbe tenere traccia almeno delle seguenti informazioni:

• Lo stato attuale della decisione (proposta, accettata, rifiutata, sostituita);
• Il contesto: quali sono le motivazioni che hanno portato a prendere o proporre questa decisione;
• La decisione: cosa verrà effettivamente implementato o scartato e come;
• Le conseguenze: cosa diventerà più facile e più difficile fare con questa decisione.

In questo modo siamo sicuri di tenere traccia di tutte le decisioni prese oltre che dalle motivazioni che hanno portato a prendere una certa scelta.

Come condividere l’Architectural Decision Record

Il primo problema da affrontare per la creazione e la gestione dell’ADR riguarda la condivisione delle informazioni all’interno dell’azienda e con tutti i team di sviluppo interessati. L’opzione ideale sarebbe quella di individuare un punto già in comune in cui gli sviluppatori condividono la documentazione, e sfruttarlo anche per l’ADR.

Nel caso in cui questo non fosse presente o non fosse ritenuto adeguato, una soluzione “grezza” consiste nell’adottare un repository dove tracciare tutte le scelte architetturali. Una scelta più strutturata consiste invece nell’utilizzo di un Developer Portal per la condivisione della documentazione, compreso l’ADR

La scelta di un Developer Portal che contenga anche l’ADR porterebbe anche i seguenti benefici:

• Una documentazione strutturata in maniera chiara e dettagliata: Un Developer Portal permette di fornire una documentazione completa e ben strutturata che riunisca in un solo punto la descrizione tecnica e di business delle funzionalità, dei sistemi, dei topic Kafka e delle API offerte dall’azienda. Questo aiuta gli sviluppatori a comprendere rapidamente come utilizzare le API nel modo corretto, riducendo il tempo necessario per l’integrazione.
• Esempi di codice e tutorial: Un Developer Portal dovrebbe offrire esempi di codice e tutorial che illustrano l’implementazione pratica delle API. Questi esempi consentono agli sviluppatori di avere una guida dettagliata su come utilizzare le API all’interno dei loro progetti.
• Promozione e adozione delle API: L’adozione di un Developer Portal aiuta a capire quali funzionalità siano già esposte e come accedervi tramite le API esistenti. Fornendo una documentazione chiara, esempi di codice e un supporto adeguato, le aziende possono quindi aumentare l’adozione delle proprie API e creare un ecosistema di sviluppatori attivo intorno ai propri servizi.
• Gestione delle versioni e delle autenticazioni: Un Developer Portal può facilitare la gestione delle versioni dei servizi, documentando quali siano le funzionalità supportate in ognuna di esse e evidenziando le versioni breaking. In questo modo gli sviluppatori potranno migrare in modo controllato alle nuove versioni. Inoltre, si possono integrare strumenti per la gestione delle autenticazioni e delle autorizzazioni delle varie API esposte, garantendone la sicurezza e il controllo degli accessi.

Conclusione

Un Architectural Decision Record ben definito può essere la chiave del successo di un progetto. Un ADR aiuta i team e tutti gli stakeholder coinvolti ad essere allineati su tutte le decisioni e sulle ragioni che le hanno determinate.. Se da un lato questo è un bene per la produttività, dall’altro è anche un beneficio per il morale del team e per la Developer Experience, facendo sentire tutti i membri parte di ciò che stanno costruendo.

La scelta di un Developer Portal come punto comune in cui memorizzare l’ADR è l’opzione migliore per aiutare i team a tenere traccia della decisione con il minor cambio di contesto possibile. Ma un Developer Portal può essere molto utile anche in altri modi. Date un’occhiata a questo articolo per scoprire 5 consigli per implementare un Internal Developer Portal nella tua azienda.