ChoiceMap, documentare processi a scelte multiple

A dicembre avevo presentato Branching Navigator, un framework per creare esperienze interattive a bivi, percorsi dove l’utente compie scelte e il contenuto si adatta di conseguenza. Era un esperimento, sviluppato in una giornata con l’assistenza di Claude, per mostrare cosa si potesse costruire collaborando con un’AI.

Da allora il progetto è cresciuto. Non è più un proof-of-concept ma uno strumento maturo, con documentazione completa, repository dedicato e funzionalità che rispondono a esigenze reali.

Il problema che risolve

Molti processi hanno scelte multiple ad ogni passo. Un ticket di assistenza segue percorsi diversi in base alla natura del problema, una procedura di compliance ha ramificazioni per ogni caso specifico, il processo di onboarding varia secondo il ruolo del nuovo dipendente.

Gli strumenti di documentazione tradizionali nascono in genere lineari nel loro modo di presentarsi, non sempre sono in grado di trasmettere la complessità delle varie situazioni. Un PDF elenca tutti i casi in sequenza, costringendo il lettore a cercare la parte rilevante. Una presentazione PowerPoint impone un percorso unico, identico per tutti. Un wiki richiede di saltare tra pagine collegate sperando di non perdersi.

Il problema non è solo rappresentare la ramificazione, ma permettere all’utente di orientarsi. Chi naviga un contenuto complesso ha bisogno di sapere dove si trova, da dove è arrivato, quali strade può ancora esplorare.

ChoiceMap affronta entrambi gli aspetti. L’utente avanza attraverso schermate che si adattano alle sue scelte, seguendo solo il percorso rilevante. E in qualsiasi momento può aprire la mappa visuale: vede la struttura ad albero, i nodi già visitati, la posizione attuale, i percorsi ancora da esplorare. Può tornare indietro o saltare a un punto già raggiunto.

Questa doppia modalità, navigazione guidata nelle schede e visione d’insieme nella mappa, riduce il disorientamento tipico dei contenuti ramificati.

Esistono strumenti professionali che fanno cose simili: Articulate Storyline, iSpring, Adobe Captivate. Funzionano bene, ma richiedono investimenti significativi dal punto di vista economico e di curve di apprendimento impegnative.

ChoiceMap è un’alternativa leggera per chi non ha bisogno di tutte quelle funzionalità.

Cosa c’è di nuovo

• Rispetto alla versione iniziale, il framework ha subito un’evoluzione significativa.

  • Nuovo nome. Il progetto si chiama ora ChoiceMap. Non è un cambiamento cosmetico: riflette il passaggio da esperimento tecnico a strumento pensato per essere usato. “Branching Navigator” descriveva il meccanismo, come funziona internamente: navigazione tra rami. È il tipo di nome che si dà quando si sta costruendo qualcosa, pensando alla struttura. “ChoiceMap” comunica cosa offre a chi lo usa: una mappa delle scelte possibili. Non richiede di sapere cos’è un albero decisionale, parla a chi ha un problema da risolvere. Il nome è anche più breve (9 caratteri contro 18), memorizzabile, pronunciabile senza esitazioni in italiano e inglese. Sono dettagli che contano quando uno strumento esce dal repository dello sviluppatore ed entra in un contesto professionale.

  • Repository dedicato. Il progetto ha ora una sua casa su GitHub, separato dagli altri simulatori. Installazione, aggiornamenti e contribuzioni sono più semplici.

  • Tre strumenti distinti. ChoiceMap è composto da tre tool che lavorano in sinergia:

    • Il Navigator visualizza gli scenari.

    • Lo Scenario Editor permette di creare contenuti con un’interfaccia visuale.

    • Il Theme Editor personalizza colori, font e branding. Ogni strumento ha un ruolo specifico.

  • Gestione dei loop. Gli scenari possono includere percorsi che tornano indietro: menu principale a cui ritornare, opzioni “riprova” dopo un errore, strutture iterative. La mappa evidenzia questi collegamenti.

  • Validazione integrata. L’editor segnala nodi orfani, scelte che puntano a destinazioni inesistenti, problemi strutturali. Prima di pubblicare, si vede subito se qualcosa non funziona.

  • Risorse allegabili. Ogni nodo può includere documenti scaricabili, link esterni, video. Non solo testo, ma materiali di supporto contestuali.

Documentazione professionale

Un’applicazione senza documentazione è un progetto personale. Può funzionare perfettamente, ma resta accessibile solo a chi l’ha costruita o a chi ha tempo per esplorare il codice.

ChoiceMap ha ora un manuale completo che copre l’intero ciclo di vita: dall’installazione alla pubblicazione, passando per la creazione degli scenari e la personalizzazione grafica.

Il manuale descrive ogni componente dell’interfaccia. Per il Navigator: la struttura delle schermate, il funzionamento della mappa, i controlli di navigazione. Per lo Scenario Editor: come creare nodi, collegare scelte, gestire risorse, interpretare i codici colore che segnalano problemi. Per il Theme Editor: la personalizzazione di colori, font, branding aziendale.

Ogni sezione include screenshot, esempi concreti, avvertenze sugli errori comuni. C’è un capitolo sulla struttura dei file JSON per chi vuole modifiche avanzate, e un riferimento rapido per chi cerca solo un promemoria.

La documentazione è disponibile in italiano e inglese, consultabile online o scaricabile in PDF.

Questo livello di documentazione distingue i progetti professionali da quelli che restano esperimenti interessanti ma difficilmente adottabili. Uno strumento ben documentato può essere usato da un team, inserito in un flusso aziendale, passato a un collega senza ore di spiegazioni.

→ Manuale italiano → English manual

Esempi di casi d’uso

• Troubleshooting guidato. “Il problema è X? → Sì → verifica Y. No → controlla Z.” Invece di un documento che elenca tutte le casistiche, l’utente risponde a domande e arriva alla soluzione. Utile per help desk, supporto tecnico, manutenzione.

• Formazione ed e-learning. Percorsi che si adattano alle risposte: chi dimostra di conoscere un argomento prosegue, chi sbaglia riceve spiegazioni prima di continuare. La valutazione diventa apprendimento. Onboarding differenziato per ruolo, compliance con feedback contestuale, corsi che si adattano al livello del partecipante.

• Decision tree aziendali. Processi di approvazione, escalation, gestione eccezioni. Ogni decisione porta al passaggio appropriato, con la documentazione di supporto allegata.

• Gaming formativo. Scenari di negoziazione, gestione conflitti, formazione sulla sicurezza. Ma anche escape room aziendali, giochi di ruolo per team building, simulazioni strategiche. Le meccaniche ludiche aumentano il coinvolgimento; la struttura a bivi permette di esplorare conseguenze senza rischi reali.

• Oltre il contesto aziendale. Lo strumento non è limitato alla formazione corporate. Una ricetta con varianti (versione vegana, per celiaci, porzioni diverse) è un albero decisionale. Un itinerario turistico con opzioni basate sulle preferenze del visitatore anche. Qualsiasi contenuto che richieda adattamento al fruitore può beneficiare di questa struttura.

Come iniziare

Il framework non richiede database, server complessi o competenze di programmazione. Per pubblicare uno scenario bastano cinque file: il Navigator, la configurazione, i default, lo scenario e il tema. Si caricano su GitHub Pages, una intranet o qualsiasi hosting statico.

La documentazione guida passo passo fino alla pubblicazione.

→ Prova il Navigator → Repository GitHub

ChoiceMap è open source, licenza MIT.

Usatelo liberamente per i vostri progetti.