Issue 10085
Disegnare non significa documentare
Un diagramma rende visibile il sistema, ma non sostituisce contesto, semantica e rationale delle decisioni.
· 5 min
Obiettivo
Distinguere diagrammi, modelli, documentazione e decision record in base alla funzione che svolgono, evitando di usare una rappresentazione visiva come sostituto universale dell'evidenza architetturale.
Parti dalla domanda, non dal formato
In architettura, un'immagine chiara può creare una pericolosa sensazione di completezza. Un diagramma mostra bene componenti, relazioni, confini e flussi; non garantisce però che chi legge conosca assunzioni, vincoli, alternative scartate o responsabilità operative. Prima di produrre un artefatto, chiedi quale domanda deve trovare risposta. Se serve capire la struttura, usa un diagramma. Se gli elementi devono avere una semantica coerente e generare viste diverse, serve un modello. Se devi accompagnare una specifica audience nell'uso o nell'evoluzione del sistema, costruisci documentazione combinando testo, viste, esempi e riferimenti. Se occorre preservare il perché di una scelta, crea un decision record con contesto, opzioni, decisione e conseguenze. In una review, non chiedere soltanto se il disegno è aggiornato: verifica quali domande restano senza evidenza.
Ogni artefatto chiarisce qualcosa e lascia altro fuori
Il diagramma è rapido da consultare e facilita l'allineamento, ma semplifica e può nascondere eccezioni o rationale. Il modello offre coerenza semantica e viste correlate, al prezzo di maggiore disciplina, strumenti e manutenzione. La documentazione può essere adattata a sviluppatori, operatori, security e stakeholderGlossarioStakeholderUna persona o un gruppo che influenza una decisione o ne sperimenta gli effetti.Apri la voce completa di business, ma diventa costosa se prova a descrivere tutto o non ha ownership. Il decision record conserva alternative e conseguenze, ma non è una descrizione sufficiente della struttura corrente. La scelta non è quindi tra un formato migliore e uno peggiore: è tra evidenze complementari, ciascuna con un costo. Mantieni solo ciò che supporta una decisione, un'implementazione o un'attività operativa concreta, e assegna ownership e momento di aggiornamento.
Un'integrazione chiara sulla lavagna, ambigua in produzione
Un'azienda introduce una piattaforma ordini che pubblica eventi verso fatturazione, magazzino e analytics. Il diagramma approvato mostra servizi, broker e flussi, quindi il team considera conclusa la documentazione. Durante l'implementazione emergono però domande irrisolte: chi possiede lo schema degli eventi, quale garanzia di consegna è richiesta, come si gestiscono duplicati e dati personali, e perché è stata preferita la consistenza eventuale. Il Solution Architect mantiene il diagramma come vista strutturale, definisce in un modello il significato di eventi e responsabilità, prepara documentazione operativa per replay e incidenti, e registra in un decision record la scelta della consistenza eventuale con alternative e conseguenze. Non produce quattro copie della stessa informazione: assegna a ogni artefatto una domanda precisa e collega gli artefatti tra loro.
Per approfondire
Fonti autorevoli per distinguere viste architetturali, documentazione e registrazione delle decisioni. • Documenting Architecture Decisions — Michael Nygard, Cognitect — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions • C4GlossarioC4Un modello di diagrammi di architettura a quattro livelli: Context, Container, Component e Code.Apri la voce completa model — Simon Brown — https://c4model.com/ • Architecture Decision Records — Technology Radar, Thoughtworks — https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records