Binario B · 8 ore

Binario B — Costruire il cruscotto

Fork del template, deploy, configurazione, verifica, presentazione pubblica. Zero righe di codice.

Quattro lezioni da due ore. Al termine la classe ha un cruscotto di dati aperti del proprio comune, pubblicato online, verificato e presentato. Non si scrive codice. Si fa un fork, si compila un file di configurazione e si controlla che i numeri siano giusti. Fork del template, deploy, configurazione, verifica, presentazione pubblica. Zero righe di codice. Richiede un account GitHub e un account Vercel intestati al docente o alla scuola.

Quale dashboard si forka. La dashboard da costruire in classe è il template vuoto magiaslab/cruscotto-comune. Non si forka questo minisito (è l'hub di divulgazione) e non si forkano i cruscotti già esistenti: oggi sono tre, il primo è San Vincenzo. San Vincenzo si usa nel binario A come oggetto di lettura: è un esemplare già online, lo stesso programma con un'altra configurazione. Apri il template su GitHub.

Account e minorenni. I termini di servizio di GitHub richiedono almeno 13 anni e quelli di Vercel almeno 16, quindi in una classe del biennio una parte degli studenti non ha l'età per aprire un account Vercel. Nel binario B l'account è del docente o della scuola e gli studenti lavorano come collaboratori del repository. Non far creare account personali agli studenti: non serve, e sposta su di loro una responsabilità che non è la loro.

Per chi è

Secondaria di secondo grado
Classi che hanno già lavorato sui dati (per esempio ASOC) e vogliono il prodotto
PCTO con committente reale

Cosa serve

Account GitHub e Vercel intestati al docente o alla scuola
Lezioni 1–2 consigliate
github.com e vercel.com non bloccati dal filtro della scuola
Un'ora di preparazione del docente prima della lezione 5

Le quattro lezioni

Lezione 5 — Dal fork al sito online

120 minuti

Obiettivi. spiegare che cos'è un repository e a che cosa serve la storia delle versioni; spiegare che cos'è un fork e perché non è una copia qualsiasi; descrivere che cosa succede quando un sito viene "messo online"; verificare che un servizio funzioni interrogando direttamente un endpoint; riconoscere che il cruscotto appena pubblicato è ancora generico, e dire che cosa manca.

Apertura (10 min). Proietta il cruscotto di San Vincenzo e poi la pagina GitHub del template. Domanda: «Questi due sono lo stesso programma. Che cosa cambia fra loro?» La risposta — cambia la configurazione, non il codice — è il concetto centrale delle lezioni 5 e 6.
Mini-lezione (20 min). Repository: una cartella con dentro tutta la storia delle sue modifiche. Fork: una copia che ricorda da dove viene. Deploy: mettere il programma su un computer sempre acceso e collegato a internet. Template: il repository di Cruscotto Comune non è il cruscotto di San Vincenzo svuotato. È un progetto pensato per essere riusato.
Attività 1 — Il fork (30 min). Dal profilo GitHub del docente, proiettato: fork di github.com/magiaslab/cruscotto-comune. Mentre si fa, chiedi a voce cosa vedono: il numero di fork, la licenza, l'ultimo commit, il file README. Sono tutte informazioni che nella lezione 1 avrebbero chiamato «metadati».
Attività 2 — Il deploy (30 min). Import del repository su Vercel, deploy. Nessuna variabile d'ambiente obbligatoria: i KPI comunali arrivano dall'MCP pubblico di AgID. Mentre la build gira, fai compilare la prima parte della scheda studente: che cosa sta succedendo in questo momento?
Attività 3 — Lo smoke test (20 min). Apri https://NOME-PROGETTO.vercel.app/api/kpi e guarda la risposta. È testo, non un sito: è il modo in cui il programma parla con altri programmi. Poi apri il sito vero. Domanda: «Di che comune è questo cruscotto?» La risposta è che non è di nessuno: è la configurazione di default.

Lezione 6 — Configurare l'identità del comune

120 minuti

Obiettivi. leggere e modificare un file JSON senza romperlo; spiegare perché configurazione e codice sono cose separate; trovare il codice ISTAT, il codice catastale e le coordinate del proprio comune; decidere quali moduli hanno senso per il proprio territorio e quali vanno spenti; riconoscere l'obbligo di citare il progetto originale.

Apertura (10 min). Proietta config/comune.example.json. È lungo e a prima vista incomprensibile: dillo tu, prima che lo pensino loro. Poi mostra che è fatto di poche cose ripetute: nomi fra virgolette, due punti, valori. Domanda: «Secondo voi quale riga fa comparire il nome del nostro comune?»
Mini-lezione (25 min). Che cos'è JSON. Tre regole: le chiavi stanno fra virgolette; i valori possono essere testo, numeri, true/false, elenchi o altri blocchi; niente virgola dopo l'ultimo elemento. Configurazione contro codice. Le chiavi che contano: istat_code, nome, provincia, regione, miur_codice_catastale, farmacie_di_turno_cod, geo.*, brand.*, site.mode, fork.maintainer_*, features.*. Menzioni: src/lib/project-origin.ts non va modificato.
Attività 1 — La configurazione su carta (20 min). Prima di toccare il computer, ogni gruppo compila su carta la propria parte (scheda studente 6): chi cerca il codice ISTAT, chi le coordinate, chi decide i moduli, chi scrive i dati del fork. Farlo su carta prima serve a due cose: si divide il lavoro e non si rompe il JSON.
Attività 2 — La configurazione vera (35 min). Si mettono insieme i pezzi in config/comune.json (copiato da config/comune.example.json). Si valida il file con un validatore JSON prima di salvarlo. Commit. Vercel ricostruisce da solo.
Attività 3 — Gli interruttori (20 min). Guardate insieme la lista features e decidete quali spegnere. Regola d'oro: un modulo acceso senza i dati giusti è peggio di un modulo spento. Un pannello vuoto o con dati di un altro comune fa danno alla credibilità di tutto il cruscotto.

Lezione 7 — Verificare: dati, accessibilità, menzioni

120 minuti

Obiettivi. verificare un valore mostrato risalendo alla fonte originale; documentare uno scostamento in modo che qualcun altro possa riprodurlo; controllare i requisiti di base dell'accessibilità di una pagina; riconoscere le responsabilità di chi pubblica dati.

Apertura (10 min). Proietta il cruscotto della classe. Frase da dire ad alta voce: «Da adesso questo sito è nostro. Se un numero è sbagliato, la colpa è nostra, non del programma.» È il passaggio dal fare al rispondere di quello che si fa.
Mini-lezione (20 min). Che cosa vuol dire verificare: prendo il numero mostrato, trovo la fonte primaria, confronto, e annoto tre cose — valore mostrato, valore alla fonte, periodo di ciascuno. Accessibilità in quattro controlli: Tab, zoom 200%, testo alternativo, contrasto. Menzioni: verificare che il cruscotto citi il progetto originale e dichiari di non essere ufficiale.
Attività A — Data quality audit (35 min). Ogni gruppo prende una sezione del cruscotto e verifica tre numeri contro la fonte primaria, compilando la scheda 7. Non serve trovare errori: serve documentare il controllo. Se un numero coincide, si scrive che coincide.
Attività B — Accessibilità (20 min). Ogni gruppo fa i quattro controlli su una pagina diversa e annota i problemi con la pagina e l'elemento preciso.
Attività C — Menzioni (10 min). Un gruppo verifica il rispetto delle regole di attribuzione e la presenza del disclaimer.
Confronto (20 min). Si mette in comune tutto. Poi la decisione più importante della lezione: che cosa facciamo con quello che abbiamo trovato? Se è un errore di configurazione → si corregge. Se è un errore del programma o della fonte → si apre una issue sul repository originale.

Lezione 8 — Raccontare i dati

120 minuti

Obiettivi. costruire una data story: domanda, dato, contesto, confronto, limite, proposta; scegliere la forma giusta per mostrare un dato; presentare a un pubblico che non conosce l'argomento; dire che cosa non si sa, senza considerarlo una sconfitta.

Apertura (10 min). Domanda diretta: «Se aveste cinque minuti davanti al sindaco, che cosa gli direste con i dati che avete raccolto?» Raccogli le prime risposte: saranno elenchi di numeri. Il lavoro della lezione è trasformarle in un discorso.
Mini-lezione (20 min). La struttura in sei mosse: domanda, dato, contesto, confronto, limite, proposta. Il punto 5 è quello che distingue una presentazione seria da una pubblicitaria. Dire quello che non si sa aumenta la credibilità, non la riduce. Scegliere la forma: quantità nel tempo → linea; confronto fra pochi elementi → barre; una proporzione → una barra sola o un numero grande. Le torte quasi mai. Il titolo del grafico dice la conclusione, non l'argomento.
Attività (50 min). Ogni gruppo prepara cinque minuti su un tema del cruscotto, seguendo le sei mosse. Chi ha fatto il binario A inserisce l'esito della richiesta di accesso civico: se è arrivata una risposta, è un risultato; se non è arrivata, è un risultato ancora migliore ed è esattamente il punto 5.
Prova generale (25 min). Due o tre gruppi presentano. Gli altri valutano con la rubrica, che hanno in mano dall'inizio del percorso. Feedback fra pari con una regola sola: prima una cosa che ha funzionato, poi una cosa da cambiare, entrambe specifiche.
Chiusura (15 min). Si decide dove e quando presentare davvero: open day, assemblea di istituto, consiglio comunale, sito della scuola. E si manda l'indirizzo del cruscotto per la vetrina delle classi.

Il prodotto finale

Un cruscotto di dati aperti del proprio comune, pubblicato online, verificato e presentato.

Materiali di questo binario

Tutti i materiali

Vai al Leggere i dati · Torna a Scuola

Progetto indipendente, non ufficiale. Non affiliato ad AgID, al Governo italiano o a un ente locale. Materiali didattici CC BY-SA 4.0.