Issue 10087
Quando un artefatto è finito?
La completezza non dipende dal numero di pagine, ma dal lavoro che il prossimo consumatore riesce a svolgere senza ricostruire informazioni essenziali.
· 5 min
Obiettivo
Valutare la completezza di un artifact in base alla capacità del prossimo consumatore di capire, decidere o agire senza dover ricostruire informazioni essenziali, evitando sia il perfezionismo sia l'ambiguità.
Definisci il traguardo dal punto di vista di chi viene dopo
Un artifact non è finito quando hai compilato tutte le sezioni del template. È finito quando una persona competente, ma assente dalle conversazioni precedenti, può usarlo per capire, decidere o agire senza inventare informazioni essenziali. Prima di produrlo, identifica quindi il prossimo consumatore e l'attività che deve svolgere: approvare una scelta, implementare un'integrazione, preparare un ambiente o gestire un servizio. Poi verifica se trova decisioni, vincoli, assunzioni, boundary, responsabilità e contratti necessari. Se deve ricostruire il perché di una scelta o chiedere chiarimenti continui, manca qualcosa. Se invece il dettaglio aggiunto non cambia una decisione, non riduce un rischio e non elimina un'ambiguità rilevante, probabilmente puoi fermarti. Non duplicare ciò che codice, configurazioni o strumenti runtime mostrano meglio: indica piuttosto la fonte autorevole.
Il costo si sposta, non scompare
Fermarsi troppo presto riduce il costo di documentazione, ma trasferisce incertezza sul team successivo: aumentano assunzioni implicite, riunioni di chiarimento, rilavorazioni e divergenze implementative. Continuare troppo a lungo può offrire più contesto, ma introduce costo di produzione e manutenzione, oltre al rischio che dettagli duplicati diventino rapidamente obsoleti. Il punto di equilibrio dipende da audience, fase e rischio. Un'interfaccia regolamentata o difficile da modificare richiede maggiore precisione; un'esplorazione reversibile può tollerare più incertezza. Anche un artifact già accettato può diventare insufficiente quando cambia il consumatore o la decisione che deve supportare.
Un diagramma che non basta al team di delivery
In un'azienda assicurativa, il Solution Architect prepara un diagramma per l'integrazione tra il portale sinistri e un servizio di valutazione esterno. Il disegno mostra sistemi e flusso principale, ma il team di delivery non trova chi possiede il contratto API, come gestire timeoutGlossarioTimeoutUn limite definito a quanto un’operazione attende prima di considerare il tentativo non riuscito.Apri la voce completa e retryGlossarioRetryUn nuovo tentativo eseguito dopo un fallimento che potrebbe essere transitorio.Apri la voce completa, quali dati personali possono attraversare il confine e cosa accade quando il fornitore non è disponibile. Il diagramma è leggibile, ma non è sufficiente per implementare. L'architetto aggiunge le decisioni su responsabilità, sicurezza, resilienzaGlossarioResilienzaLa capacità di continuare a produrre risultati utili quando componenti falliscono o le condizioni degradano.Apri la voce completa e gestione degli errori, collegando la specifica API come fonte autorevole. Non aggiunge invece classi interne o dettagli di deployment già disponibili nei repository. In review chiede a uno sviluppatore e a un referente operativo di descrivere il prossimo passo: le loro domande residue mostrano dove l'artifact è ancora ambiguo.
Usa un controllo di sufficienza prima della review
Fai una prova semplice. Chiedi a un rappresentante del prossimo gruppo di consumatori di spiegare quale decisione prenderà o quale attività avvierà usando soltanto l'artifact e le fonti collegate. Registra le domande che emergono e classificale: informazione essenziale mancante, decisione ancora aperta, dettaglio reperibile altrove oppure curiosità non necessaria allo scopo. Correggi le prime due categorie; collega la fonte autorevole per la terza; evita di espandere l'artifact per la quarta. Concludi dichiarando scopo, audience, decisioni ancora aperte e criterio di aggiornamento: rende visibile cosa significa “finito” in quel contesto.
Per approfondire
Fonti esterne autorevoli per progettare artifact orientati alle decisioni e al lavoro dei loro consumatori. • ISO/IEC/IEEE 42010:2022 — Systems and software engineering — Architecture description — ISO — https://www.iso.org/standard/74393.html • Documenting Architecture Decisions — Michael Nygard, Cognitect — https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions