ChoiceMap 2.0 – update di febbraio 2026

A fine dicembre ho pubblicato la prima versione di quello che allora si chiamava Branching Navigator, un’applicazione per creare documentazione interattiva a percorsi multipli. Era un proof-of-concept funzionante, nato per esplorare un’idea: e se invece di scrivere manuali lineari potessimo costruire mappe che l’utente attraversa facendo scelte?

Due mesi dopo, quel proof-of-concept è diventato qualcos’altro. Ha cambiato nome, ha acquisito strumenti di editing professionali, ha una documentazione completa in italiano e inglese. Ma soprattutto ha preso una direzione precisa, meno fronzoli e più sostanza.

Come esempio reale condiviso nel repository di Github ho scelto di usare ChoiceMap per mostrare cos’è ChoiceMap, così per capire cosa fa il framework lo esplori. Insomma non lo leggi ma lo navighi.

Per chi non conosce ChoiceMap

ChoiceMap è un framework per documentare processi a scelte multiple. Quando un flusso di lavoro prevede bivi, condizioni, percorsi alternativi, un documento tradizionale fatica a rappresentarlo. Puoi scrivere “se X vai al paragrafo 3, se Y vai al paragrafo 7”, ma il lettore si perde. Puoi disegnare un flowchart, ma resta un’immagine statica che non si può attraversare.

ChoiceMap risolve questo problema trasformando un albero decisionale in un’esperienza navigabile. L’utente parte da un nodo iniziale, fa una scelta, arriva a un nuovo nodo con nuove opzioni. Una mappa interattiva mostra dove si trova e quali percorsi ha già esplorato.

Il contenuto che l’utente naviga si chiama scenario. Uno scenario è un file JSON che definisce i nodi, le scelte disponibili in ciascun nodo, e le connessioni tra di essi ed è visualizzabile sia in formato scheda che in formato mappa. La visualizzazione scheda è in stile presentazione, mappa e schede interagiscono fra di loro. Non serve programmare per creare uno scenario, basta usare lo Scenario Editor incluso nel framework.

ChoiceMap non è un Learning Management System, non traccia completamenti né assegna punteggi. Non è PowerPoint, non serve per presentare ma per documentare. Non è un wiki, la struttura è definita dall’autore e non emerge dalla navigazione libera. È uno strumento specifico per un problema specifico, rappresentare processi ramificati in modo che siano comprensibili ed esplorabili.

Cosa si intende per processi complessi

Quando parlo di processi a scelte multiple non intendo quiz con risposte giuste e sbagliate, dove ogni bivio porta a un ramo separato che non si ricongiunge mai. Intendo strutture ogni nodo può portare a più percorsi, che poi possono anche convergere, dove puoi arrivare allo stesso punto da strade diverse, dove esistono loop legittimi.

Pensa a una ricetta elaborata, quella delle lasagne. Inizi con la verifica degli ingredienti, poi da quel punto partono tre strade diverse, la preparazione del ragù, della besciamella e della pasta. Tre attività parallele, ognuna con i suoi passaggi e le sue tempistiche, che alla fine convergono tutte su “assembla le lasagne”.

Un documento lineare fatica a rappresentare questa struttura. Un flowchart la rappresenta ma non la rendi navigabile. ChoiceMap ti permette di seguire ogni ramo e poi ritrovarti nel punto di convergenza.

Lo stesso schema si applica a molti contesti professionali, ad esempio:

• Un troubleshooting tecnico dove diagnosi diverse portano alla stessa soluzione.

• Un processo di onboarding dove ruoli diversi condividono alcuni passaggi ma non altri.

• Una procedura di approvazione con escalation che può rientrare nel flusso normale.

• Un percorso formativo dove chi ha già certe competenze può saltare dei moduli e ricongiungersi più avanti.

Questa capacità di gestire convergenze e loop non è un caso limite, è il motivo per cui ChoiceMap esiste. I processi reali raramente sono alberi perfetti dove ogni ramo termina in una foglia separata. Più spesso sono grafi, con nodi raggiungibili da più direzioni. Uno strumento che non gestisce questa complessità serve solo per casi semplici.

Utile, non bello

Quando si evolve un software la tentazione è aggiungere funzionalità scenografiche, effetti, animazioni, opzioni che impressionano nelle demo. Ho cercato invece di sviluppare uno strumento affidabile per chi deve creare contenuti professionali.

Questo significa mettere al centro l’informazione, non l’interfaccia. Le novità di questa versione non sono decorative, servono a chi costruisce scenari complessi e ha bisogno di controllo preciso sulla struttura. Ci sono controlli di validazione automatica per prevenire errori prima che diventino problemi. Strumenti di allineamento per chi deve gestire mappe complesse. Colorazione semantica delle connessioni per capire a colpo d’occhio la logica del flusso in strutture di decine di nodi.

Il mio desiderio è che l’utente finale non deve pensare “che bella interfaccia”, deve pensare “ho capito come funziona questo processo”. Chi amministra lo strumento non deve lottare con la gestione ma deve concentrarsi sul contenuto.

Tutto questo significa sviluppare uno strumento professionale che non deve impressionare ma deve funzionare.

Le novità concrete

ChoiceMap distingue due profili d’uso. L’amministratore crea e gestisce gli scenari usando lo Scenario Editor, definisce la struttura dei nodi, le connessioni, i contenuti. L’utente finale naviga lo scenario attraverso il Navigator, esplorando i percorsi e facendo le proprie scelte. Le novità di questa versione riguardano entrambi.

Per l’amministratore: lo Scenario Editor

La mappa

La mappa interattiva ora usa una colorazione semantica delle connessioni, i colori indicano la relazione logica tra nodi:

• Grigio per le connessioni in avanti, verso un nodo discendente

• Arancione per i loop, ritorno a un nodo già visitato nel percorso

• Viola per le connessioni laterali, verso un nodo allo stesso livello gerarchico

La colorazione è basata sulla gerarchia logica, non sulla posizione visiva. Se sposti un nodo nella mappa, il colore delle sue connessioni resta coerente con la struttura dello scenario. Questo permette di riorganizzare visivamente la mappa senza perdere informazione sulla logica del flusso.

Il canvas della mappa è ora dinamico e si espande automaticamente quando trascini nodi oltre i bordi. Niente limiti arbitrari, niente scroll frustranti.

Le nuove funzionalità per la gestione dei nodi:

• CTRL+drag per spostare i nodi con snap a griglia di 20 pixel, così gli allineamenti sono puliti senza sforzo

• SHIFT+click per selezionare più nodi contemporaneamente e attivare la fuzionalità Node repositioning

  • Allineamento orizzontale e verticale con un click

  • Distribuzione uniforme per tre o più nodi selezionati sullo stesso livello gerarchico

  • Select Level per selezionare tutti i nodi allo stesso livello gerarchico

Le schede

Nella vista schede l’amministratore gestisce il contenuto di ogni nodo, le nuove funzionalità sono:

• Override manuale dei livelli: normalmente il livello di un nodo è calcolato automaticamente dalla distanza dal nodo iniziale, ma in scenari con percorsi multipli verso lo stesso nodo puoi impostare il livello esplicitamente per controllare la gerarchia e la colorazione delle connessioni

• Riordino delle scelte con le frecce ▲/▼: permettono di cambiare l’ordine dei pulsanti senza dover cancellare e ricreare le scelte

• Risorse allegate: ogni nodo può includere materiali di supporto, link esterni, documenti scaricabili, video

Validazione automatica

L’editor ha ora una fase di controllo per evitare gli errori più comuni:

• Un nodo non può collegarsi a se stesso

• Non puoi creare un nodo senza contenuto

• Non puoi creare una scelta senza testo per il pulsante

Per l’utente finale: il Navigator

L’utente naviga lo scenario attraverso schede e mappa. La scheda mostra il contenuto del nodo corrente, formattato in markdown, e in basso i pulsanti delle scelte disponibili. Un indicatore mostra a che punto del percorso si trova, i pulsanti già cliccati cambiano colore per segnalare i rami già esplorati. La mappa offre una vista d’insieme della struttura e permette di capire dove ci si trova rispetto al percorso complessivo.

Le novità per l’utente finale:

• Backtracking: l’utente può tornare sui propri passi con il pulsante “Indietro”, ripercorrendo il percorso fatto. Utile quando si vuole esplorare una scelta alternativa senza ricominciare da capo. Il ritorno segue la cronologia delle scelte, non la struttura dello scenario, quindi funziona anche in presenza di loop.

• Risorse allegate: quando l’amministratore ha associato materiali a un nodo, l’utente li trova in una sezione dedicata sotto il contenuto. Link, documenti, video sono accessibili direttamente dalla scheda.

Vibe coding fatto bene

ChoiceMap è stato sviluppato interamente con Claude Opus 4.5 di Anthropic. Senza questa collaborazione il progetto non esisterebbe visto che non sono un programmatore, scrivere da zero un’applicazione con questa complessità sarebbe stato oltre le mie possibilità.

Ma “sviluppato con Claude” non significa “ho chiesto all’AI di farmi un’app”. Il vibe coding, come viene chiamato questo approccio, può produrre risultati molto diversi a seconda di come viene praticato.

Quello che ho cercato di fare è vibe coding con una direzione chiara. Il mio ruolo è stato quello dell’analista, definire cosa deve fare l’applicazione, valutare criticamente ogni implementazione, testare i casi limite, identificare i problemi, decidere le priorità. Claude scriveva il codice, ma le decisioni su cosa costruire e perché erano mie.

Questo richiede tempo. Ogni funzionalità passa attraverso cicli di implementazione, test, feedback, correzione. A volte si butta via tutto e si ricomincia con un approccio diverso. A volte una feature che sembrava semplice rivela complessità nascoste che richiedono ripensamenti architetturali.

Il vibe coding senza direzione produce prototipi fragili, applicazioni che funzionano nella demo ma si rompono nell’uso reale. Con direzione, con iterazione, con la volontà di non accettare il primo output che funziona, produce software usabile. ChoiceMap è la dimostrazione che la combinazione può funzionare, ma richiede che la parte umana resti nel ciclo come guida, non come spettatore.

ChoiceMap spiega ChoiceMap

Lo scenario di default del repository, usato anche come demo live, è una guida interattiva al framework stesso. Non è solo un esercizio meta-circolare, è il modo più efficace per capire cosa può fare ChoiceMap.

Invece di leggere un README lineare, esplori. Vuoi capire come funziona lo Scenario Editor? Segui quel ramo. Ti interessa la struttura dei file JSON? C’è un percorso dedicato. In molte schede sono linkati i capitoli o anche i paragrafi di approfondimento del manuale che ho sviluppato per accompagnare il rilascio.

Questa scelta riflette la filosofia del progetto: se uno strumento serve a creare esperienze navigabili, la sua stessa documentazione dovrebbe essere navigabile.

Il manuale

In occasione di questa versione ho rivisto completamente il manuale, disponibile sia in italiano che in inglese. Non è solo un aggiornamento per descrivere le nuove funzionalità ma ho anche riorganizzato la struttura, ampliando le spiegazioni. Il percorso dall’installazione alla pubblicazione del primo scenario è ora più lineare e documentato passo per passo. Per chi preferisce un riferimento completo alla guida interattiva, il manuale copre tutti gli aspetti del framework in modo sistematico.

Come provarlo

ChoiceMap è open source, licenza MIT. Non richiede server, database, o build process. Funziona con file statici su qualsiasi hosting.

• Demo live la guida interattiva al framework

• Repository GitHub codice, esempi, istruzioni

• Documentazione italiana manuale completo con tutorial

• English documentation full manual with tutorials

Per iniziare bastano cinque file e un hosting statico. GitHub Pages va benissimo.

Prossimi passi

Il progetto è in evoluzione. Le idee per le prossime versioni non mancano, ma preferisco non fare promesse: vedremo cosa emerge dall’uso reale e dai feedback.

Se avete scenari interessanti da condividere, problemi da segnalare, o semplicemente curiosità, il repository è aperto. I contributi sono benvenuti.