Issue 10083
Un Solution Architect non produce documenti
Produce l'evidenza minima necessaria per capire, attuare e governare una decisione.
· 5 min
Obiettivo
Capire che il valore degli artifact architetturali non sta nel numero di documenti prodotti, ma nella capacità di ridurre incertezza, rendere esplicite le decisioni e consentire ad altri di costruire, operare e governare una soluzione.
Parti dalla domanda, non dal template
Un artifact architetturale è utile quando consente a qualcuno di prendere una decisione o svolgere un'attività con meno ambiguità. Prima di aprire un template, chiarisci quale domanda deve ricevere risposta, chi userà l'evidenza e quale conseguenzaGlossarioConseguenzaUn effetto atteso, positivo o negativo, di una decisione.Apri la voce completa avrebbe una risposta poco chiara. Se devi confrontare alternative, prepara una tabella di trade-offGlossarioTrade-offUno scambio in cui migliorare un risultato ne indebolisce o ne rende più costoso un altro.Apri la voce completa; se devi conservare il rationale, usa un decision record; se due team devono integrarsi, definisci un contratto verificabile; se il rischio riguarda esercizio e resilienzaGlossarioResilienzaLa capacità di continuare a produrre risultati utili quando componenti falliscono o le condizioni degradano.Apri la voce completa, mostra dipendenze, failure scenarioGlossarioScenarioUna situazione concreta usata per testare come un design o una decisione si comporta.Apri la voce completa e assunzioni operative. Scegli poi il formato più adatto: testo per rationale e vincoli, diagrammi per boundary e relazioni, matrici per confronti e ownership, formati machine-readable per contratti verificabili. Il controllo finale è semplice: una persona non presente alla discussione dispone dell'evidenza minima per capire, implementare, verificare e mantenere la decisione?
Minimo non significa superficiale
Ridurre gli artifact diminuisce duplicazioni, tempi di aggiornamento e falsa sensazione di controllo. Il rischio, però, è confondere la sintesi con l'omissione: una decisione critica senza contesto, alternative e conseguenze resta fragile. Documentare di più può aiutare in ambienti regolamentati, in transizioni complesse o quando molti team devono coordinarsi, ma aumenta il costo di manutenzione e la probabilità di versioni incoerenti. Anche il luogo conta: una whiteboard accelera l'esplorazione, mentre un repository versionato offre tracciabilità e vicinanza al software. Non serve scegliere sempre lo stesso strumento. Serve calibrare dettaglio, formato e ciclo di vita sulla durata della decisione, sul rischio e sull'audience.
Una migrazione pagamenti senza il dossier enciclopedico
Un'azienda retail deve migrare il servizio pagamenti da un'applicazione monolitica a una piattaforma condivisa, coinvolgendo team applicativi, sicurezza e operations. Il processo standard richiede un documento esteso, ma le incertezze reali sono quattro: confini di responsabilità, alternative di integrazione, requisiti di resilienza e sequenza della transizione. Il Solution Architect costruisce quindi un piccolo insieme coerente di evidenze: una context view per responsabilità e dipendenze, una tabella di trade-off tra chiamate sincrone ed eventi, un ADRGlossarioADRUn record durevole di una decisione architetturale e del ragionamento che l’ha guidata.Apri la voce completa per la scelta, un contratto API versionato e una sequenza degli stati di migrazione con rollback. Sicurezza e operations partecipano alla revisione degli scenari di errore. Il risultato non è meno rigoroso: ogni artifact ha un utilizzatore, risponde a una domanda e può evolvere vicino alla soluzione. Vengono esclusi, invece, diagrammi duplicati e sezioni standard che non influenzano alcuna decisione.
Per approfondire
Fonti autorevoli per approfondire la documentazione delle decisioni e la costruzione di viste architetturali orientate all'audience. • Documenting Architecture Decisions — Michael Nygard, Cognitect — https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions • ISO/IEC/IEEE 42010:2022, Systems and software engineering — Architecture description — ISO — https://www.iso.org/standard/74393.html