Perché la Documentazione Tecnica Non Funziona (e Cosa Fare Instead)

Siamo onesti: quante volte ti è capitato di aprire un documento di architettura e sentirti gli occhi che si chiudono dopo due paragrafi?

La documentazione tecnica tradizionale fallisce nel suo compito più semplice — spiegare perché un sistema esiste e come funziona nella realtà.

Domain Storytelling ribalta completamente questo approccio.

Cos'è il Domain Storytelling?

È una tecnica collaborativa dove team tecnici, esperti di dominio e stakeholder mappano il funzionamento di un sistema attraverso... storie. Niente diagrammi UML incomprensibili o pagine di specifiche infinite. Qui crei narrative visive che mostrano chi fa cosa, quando e perché.

Immagina di scrivere un flowchart che si legge come il capitolo di una giornata tipo.

Identifichi gli attori (persone e sistemi coinvolti), le loro attività (cosa fanno davvero) e gli oggetti del lavoro (cose che creano, modificano o usano). Poi intrecci tutto in una sequenza visiva che chiunque — sviluppatore o meno — può capire.

Perché Dovrebbe Importare agli Sviluppatori?

La verità è questa: la maggior parte del technical debt non nasce da codice scritto male. Nasce da disallineamento.

Costruisci quello che credi il cliente volesse, loro volevano qualcosa di completamente diverso, e improvvisamente stai facendo refactoring alle 2 di notte.

Domain Storytelling intercetta questo disallineamento sul nascere. Quando puoi vedere il processo di business mappato visivamente, le lacune, le ridondanze e gli equivoci diventano evidenti all'istante.

Per i sistemi event-driven poi — ed è qui che entra in gioco EventSourcingDB — capire il flusso narrativo degli eventi è fondamentale. Un'architettura event-sourced vive o muore in base a quanto bene cattura il comportamento reale del dominio. Se sbagli la storia, passerai mesi a ritoccare il tuo schema degli eventi.

I Vantaggi Pratici

Onboarding più rapido: i nuovi membri del team capiscono lo scopo di un sistema in minuti, non in giorni.

Meno rework: tutti sono d'accordo sul "cosa" prima che qualcuno scriva una riga di codice.

Comunicazione migliore con gli stakeholder: i partner non tecnici possono contribuire davvero alla pianificazione.

Event modeling più chiaro: per chi lavora con event sourcing, Domain Storytelling rende i confini degli aggregate e le relazioni tra eventi intuitivi a colpo d'occhio.

Da Dove Partire

Non servono strumenti complicati. Una lavagna bianca, qualche post-it e la voglia di ascoltare gli esperti di dominio ti portano sorprendentemente lontano.

La pratica base è semplice: chiedi "cosa succede dopo?" finché non hai mappato un intero processo di business. Fa' attenzione a dove le persone esitano, non sono d'accordo o dicono "in realtà è più complicato di così" — quei momenti rivelano la complessità nascosta nel tuo dominio.

Il Principio Si Applica Ovunque

Che tu stia costruendo una semplice landing page o un sistema distribuito complesso sulla tua cloud hosting platform, il principio vale: capire la storia umana dietro la soluzione tecnica porta a risultati migliori.

Il tuo domain model è buono quanto la tua comprensione del dominio stesso. Domain Storytelling ti dà un modo strutturato e ripetibile per costruire questa comprensione in modo collaborativo.

La prossima volta che pianifichi una nuova funzionalità o un nuovo sistema, salta il documento requirements lungo come un romanzo. Prendi dei pennarelli. Racconta prima la storia.

Hai mai provato Domain Storytelling nei tuoi progetti? Condividi la tua esperienza nei commenti — vorremmo sapere cosa ha funzionato (e cosa no) per il tuo team.