Definizione breve

Documento breve che traccia una decisione di architettura software: il contesto che l'ha resa necessaria, le opzioni considerate, l'opzione adottata e le conseguenze accettate. Abbreviato in ADR.

Definizione dettagliata

La pratica viene dai team di sviluppo, dove è ampiamente consolidata. La sua ragion d'essere è temporale: diversi mesi o anni dopo, qualcuno che non c'era deve poter capire perché è stata fatta una scelta tecnica — perché è stata introdotta una coda di messaggi per elaborare certi messaggi in modo asincrono, quali opzioni sono state scartate, cosa la scelta permette e cosa vincola.

Negli articoli di questo blog, il termine è usato come riferimento d'origine più che per sé stesso: serve a situare il Product Decision Record, che ne riprende la struttura spostando l'oggetto dal componente tecnico alla regola di prodotto. La differenza di natura sta in ciò che viene tracciato — un ADR fissa una scelta di costruzione del sistema, un PDR una regola applicabile a situazioni future.

L'ADR ha una proprietà che il vocabolario di prodotto riprende male: documenta abitualmente lavori senza valore di business visibile. Un mese di lavoro su una tecnologia di coda messaggi non consegna nulla all'utente finale eppure può eliminare un collo di bottiglia, assorbire da dieci a trenta volte il carico semplicemente aggiungendo server, e permettere ai commerciali di vendere nuovi accessi clienti.

Uso nel dominio

Il termine compare nelle discussioni sulla memoria tecnica di un team, sulla giustificazione dei lavori senza rilascio funzionale, e come termine di paragone non appena si propone uno strumento equivalente sul lato del prodotto.

Sinonimi e varianti

«Decisione di architettura», «ADR», «diario di architettura». Il plurale «gli ADR» designa comunemente il registro intero tanto quanto le sue voci.

Da non confondere con

• Product Decision Record — Product Decision Record — stessa forma documentale applicata a una regola di decisione di prodotto trasversale; non impegna alcuna scelta di costruzione.
• Documentazione di architettura — descrizione dello stato del sistema così com'è; l'ADR descrive un momento di scelta e non si aggiorna quando il sistema evolve.
• Specifica tecnica — descrizione di ciò che bisogna realizzare e di come farlo; discende da una decisione di architettura, non la giustifica.

Esempi

«Un'applicazione subisce un aumento di carico. […] Il team decide allora di implementare una tecnologia di coda messaggi per elaborare certi messaggi in modo asincrono.» — la situazione tipica che l'ADR registra.

«Perché è stata presa? Quali opzioni sono state scartate? Quali conseguenze si accettano? Cosa permette? Cosa vincola?» — le domande a cui la voce risponde.

Ambiguità / dibattiti

L'uso corrente esita sull'immutabilità: alcuni team tengono i loro ADR come documenti fissi e segnano le sostituzioni, altri li aggiornano come una documentazione viva. Il senso adottato qui segue la prima pratica, che è anche quella ripresa dal PDR.