README iniziale: cosa deve spiegare subito

Il README non è un foglio di copertina.

È il primo punto di orientamento del progetto. Quando uno studente, un compagno o un docente apre la cartella del Registro del laboratorio, deve capire subito tre cose:

• che cosa fa il progetto;
• come si avvia;
• che cosa esiste già e che cosa verrà costruito dopo.

In un laboratorio di architettura questa chiarezza è fondamentale. Se il progetto non è spiegato, ogni file sembra isolato. Se invece il README è scritto bene, il percorso diventa leggibile: si capisce da dove si parte, dove si sta andando e quali decisioni sono già state prese.

Obiettivo della lezione

Alla fine devi avere un README iniziale che spiega:

• il problema del Registro del laboratorio scolastico;
• lo scopo didattico del progetto;
• come aprire o avviare l’applicazione;
• quali funzionalità sono previste;
• qual è lo stato attuale del lavoro;
• quali regole saranno importanti;
• quale stack tecnico userai;
• quali file esistono nella struttura iniziale.

Non deve essere lungo. Deve essere utile.

Un README utile non racconta tutto il corso. Aiuta chi entra nel progetto a fare il primo passo senza chiedere spiegazioni a voce.

Il README come mappa del percorso

In questo corso il progetto cresce a piccoli passi. Per questo il README deve distinguere bene:

• funzionalità previste, cioè quello che il Registro dovrà saper fare nel percorso;
• stato attuale, cioè quello che funziona davvero oggi;
• prossimi passi, cioè quello che verrà affrontato nelle lezioni successive.

Senza questa distinzione nasce confusione.

Se nel README scrivi solo:

Il progetto gestisce strumenti, prestiti, guasti e salvataggio dati.

sembra che tutto sia già pronto.

Meglio scrivere:

Il progetto arriverà a gestire strumenti, prestiti, guasti e salvataggio dati.
In questa fase iniziale mostra solo una lista di strumenti di esempio.

Questa frase è più onesta e più didattica: fa capire che il percorso è progressivo.

Struttura minima consigliata

All’inizio puoi usare questa struttura:

# Registro del laboratorio scolastico

## Obiettivo del progetto

## Come si avvia

## Funzionalità previste

## Stato attuale

## Regole da verificare

## Scelta dello stack

## Struttura iniziale

## Prossimi passi

Queste sezioni bastano. Più avanti aggiungerai test, diagrammi, decisioni tecniche e istruzioni più precise.

Per ora il README deve essere una mappa breve, non un manuale.

Obiettivo del progetto

La sezione Obiettivo del progetto deve spiegare il problema in linguaggio semplice.

Esempio:

## Obiettivo del progetto

Il Registro del laboratorio scolastico serve a gestire strumenti e dispositivi
usati durante le attività didattiche.

Il progetto permetterà di registrare strumenti, cercarli per nome, categoria
o stato, gestire prestiti, chiudere prestiti e aprire segnalazioni di guasto.

Nel corso useremo questo progetto per imparare a separare interfaccia,
casi d'uso, regole di dominio e salvataggio dati.

Questa sezione deve rispondere a una domanda concreta:

perché questo progetto esiste?

Evita frasi generiche:

Questo progetto serve a gestire dati.

Gestire quali dati? Per chi? Con quali operazioni? In quale contesto?

Nel README devi usare le parole del problema: strumenti, dispositivi, laboratorio, prestiti, guasti, stati.

Come si avvia

La sezione Come si avvia deve essere verificabile.

Se il progetto si può aprire direttamente nel browser:

## Come si avvia

Aprire `index.html` nel browser.

Se il browser blocca i moduli JavaScript caricati da file locale, usa un piccolo server locale:

## Come si avvia

Dalla cartella del progetto eseguire:

```bash
python3 -m http.server 5173
```

Poi aprire:

```txt
http://localhost:5173
```

Il comando scritto nel README deve funzionare davvero nel tuo ambiente.

Una regola semplice:

se una persona copia il comando e non parte nulla, il README va corretto

Funzionalità previste

Questa sezione descrive la direzione del progetto.

Non è una promessa che tutto sia già implementato. È l’elenco delle capacità che costruiremo durante il percorso.

Esempio:

## Funzionalità previste

- registrare strumenti o dispositivi;
- cercare strumenti per nome, categoria o stato;
- segnare strumenti come disponibili, in prestito, guasti o in manutenzione;
- registrare prestiti;
- chiudere prestiti;
- aprire segnalazioni di guasto;
- salvare i dati prima in memoria e poi in localStorage o JSON;
- mostrare messaggi comprensibili all'utente;
- testare le regole principali.

Questa lista aiuta lo studente a capire il percorso. Prima vedrà una lista semplice. Poi aggiungerà ricerca, stati, prestiti, regole, persistenza e test.

Il progetto non appare più come una raccolta di lezioni sparse: diventa un’applicazione che cresce.

Stato attuale

Questa sezione è piccola ma importantissima.

Serve a dire che cosa funziona davvero in questo momento.

Esempio:

## Stato attuale

Al momento il progetto mostra una lista iniziale di strumenti caricati da
`src/datiIniziali.js`.

Non sono ancora presenti ricerca, prestiti, salvataggio dati o test automatici.
Queste parti verranno aggiunte nelle lezioni successive.

Questa sezione evita un equivoco frequente: leggere il README e aspettarsi un’applicazione già completa.

Ogni volta che il progetto cresce, aggiorna lo stato attuale. Bastano poche righe.

Regole da verificare

Le regole non sono dettagli grafici. Sono comportamenti che il sistema deve rispettare.

Per il Registro del laboratorio, alcune regole sono:

## Regole da verificare

- uno strumento guasto non può essere prestato;
- uno strumento già in prestito non può essere prestato di nuovo;
- un prestito chiuso non può essere chiuso di nuovo;
- uno strumento deve avere nome, categoria e stato;
- gli stati ammessi sono: disponibile, in prestito, guasto, in manutenzione;
- una segnalazione di guasto deve indicare almeno il motivo.

Scrivere queste regole nel README serve a preparare il lavoro futuro.

Più avanti diventeranno:

• funzioni nel dominio;
• controlli nei casi d’uso;
• test automatici;
• messaggi comprensibili per l’utente.

Non serve ancora implementarle tutte. Serve però iniziare a riconoscerle.

Scelta dello stack

Qui spieghi perché il progetto parte con uno stack semplice.

Esempio:

## Scelta dello stack

Useremo JavaScript modulare nel browser, senza framework.

La scelta permette di concentrarsi sulla separazione delle responsabilità:
interfaccia, casi d'uso, dominio e persistenza.

I dati saranno prima in memoria e poi in localStorage o JSON.

Questa sezione risponde in anticipo a domande legittime:

• perché non usiamo subito React?
• perché non c’è ancora un database?
• perché i dati sono in memoria?
• perché separiamo file piccoli anche se il progetto è ancora semplice?

La risposta è: perché l’obiettivo della fase iniziale è capire le responsabilità, non nasconderle dentro strumenti più grandi.

Struttura iniziale

Documenta la struttura attuale, anche se è piccola.

Usa un blocco come questo:

## Struttura iniziale

```txt
registro-laboratorio/
  README.md
  index.html
  src/
    main.js
    datiIniziali.js
```

- `index.html`: pagina minima dell'applicazione;
- `src/main.js`: punto di ingresso JavaScript;
- `src/datiIniziali.js`: strumenti di esempio usati all'avvio.

Questa sezione deve cambiare quando cambia il progetto.

Quando introdurrai domain, application, infrastructure e presentation, il README dovrà spiegare il nuovo significato delle cartelle.

Prossimi passi

La sezione Prossimi passi aiuta lo studente a capire dove andare dopo.

Esempio:

## Prossimi passi

1. Verificare che l'ambiente funzioni.
2. Costruire una prima versione fragile del registro in un solo file.
3. Osservare quali responsabilità iniziano a mescolarsi.
4. Separare progressivamente dominio, casi d'uso, infrastruttura e interfaccia.

Questa sezione non deve diventare l’indice completo del corso. Deve solo indicare la direzione immediata.

Un README debole e un README utile

README debole:

# Registro

Progetto scuola.

Non aiuta. Non spiega il problema, non dice come si avvia, non indica lo stato del lavoro.

README utile:

# Registro del laboratorio scolastico

Applicazione didattica per gestire strumenti, prestiti e guasti nel laboratorio.
Il progetto serve a imparare a separare interfaccia, casi d'uso, dominio e persistenza.

È ancora breve, ma dà coordinate reali.

Un buon README non deve impressionare. Deve orientare.

Attività guidata

Apri README.md e costruisci le sezioni minime:

# Registro del laboratorio scolastico

## Obiettivo del progetto

## Come si avvia

## Funzionalità previste

## Stato attuale

## Regole da verificare

## Scelta dello stack

## Struttura iniziale

## Prossimi passi

Poi compila ogni sezione con contenuti veri.

Non copiare frasi che non corrispondono al tuo progetto. Se il progetto non ha ancora localStorage, non scrivere che salva in localStorage. Se non ha ancora test, non scrivere che i test sono presenti.

Controllo incrociato

Dopo aver scritto il README, fai una prova semplice.

Passalo a un compagno e chiedigli di rispondere senza aprire altri file:

• che cosa fa il progetto?
• come si avvia?
• che cosa funziona già?
• che cosa non è ancora pronto?
• quali sono le regole più importanti?
• dove sono i dati iniziali?
• qual è il prossimo passo?

Se il compagno non riesce a rispondere, il README non è ancora abbastanza chiaro.

Non è un fallimento: è esattamente il motivo per cui lo scriviamo presto.

Micro-sfida

Trova una frase generica nel tuo README e rendila concreta.

Esempio generico:

Il sistema gestisce dispositivi.

Versione più utile:

Il sistema registra strumenti del laboratorio, li cerca per nome, categoria o stato
e permette di segnalarli come disponibili, in prestito, guasti o in manutenzione.

Vincolo: nella nuova frase devono comparire almeno due parole del dominio, per esempio strumento, prestito, guasto, stato, laboratorio.

Prodotto da ottenere

Alla fine della lezione devi avere:

• un README leggibile;
• una sezione di avvio verificabile;
• una lista di funzionalità previste;
• una sezione sullo stato attuale;
• almeno cinque regole da verificare;
• una spiegazione breve dello stack;
• una descrizione della struttura iniziale;
• un elenco di prossimi passi immediati.

Domande di comprensione

Rispondi per iscritto:

• Perché il README deve distinguere funzionalità previste e stato attuale?
• Quale problema nasce se documenti funzionalità che non esistono ancora?
• Perché scrivere le regole nel README aiuta i test futuri?
• Che cosa deve capire una persona che apre il progetto per la prima volta?
• Quale sezione del README cambierà quando introdurremo i livelli architetturali?

Controllo finale

La lezione è completata quando puoi dire sì a queste domande:

• il README ha un titolo chiaro;
• spiega il problema del Registro del laboratorio;
• indica come avviare il progetto;
• distingue funzionalità previste e stato attuale;
• contiene regole da verificare;
• spiega perché usiamo JavaScript modulare senza framework;
• descrive la struttura iniziale dei file;
• indica il prossimo passo del percorso;
• una persona esterna può orientarsi senza chiederti tutto a voce.

Nel prossimo passo controlleremo l’ambiente di lavoro: browser, editor, DevTools, Git e localStorage. Prima di aggiungere logica, dobbiamo essere sicuri che tutti riescano ad avviare e osservare il progetto.