Architecture Decision Record

Active theme: Light

← documenti

Suggerimenti per scrivere buoni ADR

Caratteristiche di un buon ADR:

  • Motivazione: spiega perché si sta eseguendo la AD. Può includere il contesto (vedi sotto), pro e contro di diverse opzioni possibili, confronti di funzionalità, discussioni su costi e benefici e così via.

  • Specifico: ogni ADR dovrebbe riguardare una AD, non più AD.

  • Con timestamp: indica quando è stata scritta ogni voce dell'ADR. Questo è particolarmente importante per gli aspetti che possono cambiare nel tempo, come costi, tempistiche, espansione e così via.

  • Immutabile: non modificare le informazioni esistenti in un ADR. Modifica invece l'ADR aggiungendo nuove informazioni, oppure sostituisci l'ADR creando un nuovo ADR.

Caratteristiche di una buona sezione "Contesto" in un ADR:

  • Descrive la situazione dell'organizzazione e le priorità aziendali.

  • Include la motivazione e le considerazioni basate sulla composizione sociale e tecnica del team.

  • Include compromessi pertinenti, espressi in termini che corrispondono a esigenze e obiettivi.

Caratteristiche di una buona sezione "Conseguenze" in un ADR:

  • Descrive ciò che deriva dalla presa della decisione. Possono essere effetti, risultati, consegne, azioni successive e così via.

  • Include informazioni sugli ADR successivi. È relativamente comune che un ADR faccia sorgere la necessità di altri ADR. Per esempio, se un ADR compie una scelta ampia e generale, questa può far nascere la necessità di decisioni più piccole.

  • Include un processo di revisione a posteriori. È comune che i team rivedano ogni ADR dopo un mese, confrontino le informazioni dell'ADR con ciò che è realmente accaduto e imparino e crescano da questo.

Un nuovo ADR può sostituire un ADR precedente:

  • Quando viene presa una AD che sostituisce o invalida un ADR precedente, dovrebbe essere scritto un nuovo ADR