Controllo README e istruzioni di avvio

Questa lezione appartiene al Modulo 23 — Revisione finale.

Il lavoro continua il progetto guida, il Registro del laboratorio scolastico. In questa lezione verifichi che il README permetta a una persona che non ha mai visto il progetto di avviarlo correttamente su un computer nuovo.

Obiettivo della lezione

Seguire le istruzioni del README come se fossi un nuovo utente — senza usare la memoria del progetto — e documentare ogni punto in cui le istruzioni sono incomplete, imprecise o mancanti.

Alla fine devi avere: un README aggiornato che permette l’avvio del Registro da zero, testato da almeno una persona esterna.

Il test del “nuovo computer”

Il test più efficace per le istruzioni di avvio è fingere di usare un computer nuovo. Questo significa:

• non usare shortcut o percorsi che conosci a memoria
• non saltare passi “ovvi” — per un nuovo utente non sono ovvi
• non completare le istruzioni dalla memoria — se manca un passo, annotalo

Un README che passa questo test permette a qualunque studente (o al docente) di avviare il Registro senza chiedere aiuto.

Struttura minima del README per il Registro

Un README del Registro deve avere almeno queste sezioni:

• Descrizione — cos’è il Registro e cosa fa
• Struttura del progetto — le quattro cartelle e il loro ruolo
• Come avviare — passi per aprire il progetto nel browser
• Dati di esempio — come caricare dati iniziali per testare
• Come eseguire i test — comando Node.js per i test automatici
• Limiti noti — cosa non funziona o non è implementato

Procedura guidata

1. Apri il README attuale del Registro.
2. Leggi le istruzioni di avvio seguendole passo per passo senza usare la memoria.
3. Annota ogni punto dove ti fermi o devi indovinare.
4. Correggi le istruzioni aggiungendo i passi mancanti.
5. Chiedi a un compagno di seguire le istruzioni senza il tuo aiuto.
6. Documenta i problemi trovati dal compagno e correggi.

Attività in classe

Compila questa scheda durante il test:

## Test istruzioni README

Passo 1 delle istruzioni: (copia qui)
Hai potuto seguirlo senza aiuto? sì / no — problema trovato:

Passo 2: (copia)
Problema:

[...]

Passi mancanti trovati:

Sezioni mancanti nel README:

Il compagno ha avviato il Registro seguendo solo il README? sì / no

Spiegazione guidata per studiare

Un README scritto dall’autore del progetto è sempre sospetto: l’autore sa già come funziona e salta inconsapevolmente i passi che gli sembrano ovvi. Il README deve essere scritto pensando a chi non sa nulla del progetto — e deve essere testato da quella persona.

Le istruzioni di avvio per il Registro sono particolarmente importanti perché il progetto è browser-only ma potrebbe richiedere un server locale (Live Server, http-server) per gestire i moduli ES6. Questo passo è spesso dimenticato.

Passo per passo nel progetto

1. Apri il README (o crealo se non esiste). La struttura di base:

# Registro del laboratorio scolastico

Sistema di gestione strumenti del laboratorio scolastico.
Permette di registrare strumenti, gestire prestiti e segnalare guasti.

## Struttura del progetto

src/
  domain/        — modelli e regole di business (Strumento, Prestito)
  application/   — casi d'uso (apriPrestito, cercaStrumenti, ...)
  infrastructure/ — adapter per localStorage
  presentation/  — gestori eventi UI
main.js          — punto di composizione

## Come avviare

1. Clona o scarica il repository
2. Installa le dipendenze (se presenti): npm install
3. Avvia un server locale:
   - con VS Code: installa l'estensione "Live Server", click destro su index.html → Open with Live Server
   - con Node.js: npx http-server . -p 8080
4. Apri il browser su http://localhost:8080

Nota: il progetto usa moduli ES6 e richiede un server HTTP locale.
Non funziona aprendo index.html direttamente (protocollo file://).

## Dati di esempio

Per caricare dati di esempio, apri la console del browser (F12) e incolla:

[inserisci qui lo script di caricamento dati]

## Come eseguire i test

node src/test/test-casi-limite.js
node src/test/test-con-dati-esempio.js

## Limiti noti

- Nessuna autenticazione — il ruolo è impostato manualmente in main.js
- I dati non sono sincronizzati tra schede diverse dello stesso browser
- [aggiungi altri limiti specifici del tuo progetto]

1. Verifica ogni sezione contro il codice reale. Controlla:

   • il percorso delle cartelle è corretto?
   • il comando di avvio funziona davvero?
   • i comandi di test producono output leggibile?
   • lo script di caricamento dati è aggiornato?

2. Fai il test del “nuovo computer”: apri un terminale pulito, segui le istruzioni del README passo per passo. Appunta dove ti blocchi.

3. Chiedi a un compagno di fare lo stesso test e di non chiederti aiuto. Conta quante volte si ferma.

4. Per il problema più comune — i moduli ES6 che non funzionano con file:// — aggiungi una nota chiara nel README:

## Problema comune: "Cannot use import statement"

Se apri index.html direttamente nel browser e vedi questo errore,
il browser sta bloccando i moduli ES6 per motivi di sicurezza.

Soluzione: usa un server locale (vedi "Come avviare" sopra).

1. Verifica che i link nel README puntino a file che esistono:

# cerca i link markdown nel README e verifica che i file esistano
grep -oP '\[.*?\]\(\K[^)]+' README.md | while read link; do
  [ -f "$link" ] && echo "OK: $link" || echo "MANCANTE: $link"
done

Esempio — sezione “Come avviare” ben scritta

## Come avviare

### Prerequisiti

- Un browser moderno (Chrome, Firefox, Edge — non Internet Explorer)
- Node.js installato (per il server locale e i test)

### Passi

1. Scarica il progetto (o clona con git clone [url])
2. Apri il terminale nella cartella del progetto
3. Avvia il server locale:

   npx http-server . -p 8080

   Se npm non è installato, usa VS Code con l'estensione "Live Server"

4. Apri http://localhost:8080 nel browser
5. Il Registro è pronto. Carica i dati di esempio con lo script in console (vedi sezione "Dati di esempio")

### Verifica

Dovresti vedere la pagina principale con i pulsanti: Registra, Presta, Restituisci, Segnala Guasto.
Se la pagina è bianca o la console mostra errori, controlla che il server locale sia avviato.

Prova di comprensione

Rispondi per iscritto:

• Quali passi mancavano nel README originale?
• Perché i moduli ES6 non funzionano con il protocollo file://?
• Il tuo compagno è riuscito ad avviare il Registro seguendo solo il README? Cosa ha bloccato?
• Qual è la sezione del README che hai riscritto di più e perché?

Errori da evitare

• scrivere “apri index.html nel browser” senza specificare che serve un server locale;
• non testare le istruzioni su un ambiente pulito;
• dimenticare di aggiornare le istruzioni quando cambia la struttura del progetto;
• scrivere istruzioni per Windows ma non per Mac (o viceversa).

Prodotto da consegnare

Il README aggiornato con tutte le sezioni presenti e testate. Come verifica: il compagno ha avviato il Registro da zero seguendo solo il README, senza domande.

Checklist di chiusura

• il README ha tutte le sezioni: descrizione, struttura, avvio, dati di esempio, test, limiti;
• le istruzioni di avvio includono il server locale e spiegano perché è necessario;
• i comandi di test sono stati eseguiti e producono output corretto;
• un compagno ha testato le istruzioni senza aiuto;
• i problemi trovati dal compagno sono stati corretti.

Risultato atteso

Ho testato le istruzioni del README su un ambiente pulito.
Problemi trovati: [lista].
Correzioni applicate: [lista].
Il compagno ha avviato il Registro in [X] minuti seguendo solo il README.
Il README finale ha 6 sezioni complete e funzionanti.