Il README è il primo file che una persona apre quando incontra un progetto: un repository di codice, uno script condiviso con i colleghi, una cartella di automazioni lasciata a chi verrà dopo. In pochi secondi deve rispondere a tre domande: che cos'è, mi serve, come lo faccio funzionare.
Un README scritto male non fa danni visibili subito. Li fa dopo: richieste di aiuto ripetute, installazioni sbagliate, un progetto abbandonato perché nessuno, nemmeno l'autore sei mesi dopo, ricorda come avviarlo.
La regola dei trenta secondi
Chi apre il README legge l'inizio e decide se continuare. Le prime righe devono quindi contenere:
- il nome del progetto;
- una frase che dica che cosa fa, in termini concreti;
- per chi è pensato o in quale situazione è utile.
Un esempio:
# rinomina-scansioni
Rinomina in blocco i PDF prodotti dallo scanner dell'ufficio usando
la data e il numero di protocollo letti nella prima pagina.
Pensato per chi archivia ogni giorno decine di documenti acquisiti.
Confrontatelo con un inizio tipico come «Questo progetto è uno strumento potente e flessibile per la gestione dei documenti»: non dice nulla di verificabile.
Le sezioni essenziali
Non tutti i progetti hanno bisogno di tutto, ma questa struttura copre la maggior parte dei casi:
- Descrizione: cosa fa, eventualmente una cattura dello schermo o un esempio di risultato.
- Requisiti: sistema operativo, versioni di linguaggi o programmi necessari.
- Installazione: i comandi esatti, nell'ordine in cui vanno eseguiti.
- Uso: l'esempio più comune, da copiare e incollare.
- Configurazione: opzioni, variabili d'ambiente, file di impostazioni.
- Problemi noti e soluzioni: gli errori che si incontrano più spesso.
- Come contribuire o segnalare problemi, se il progetto è condiviso.
- Licenza, se il codice è distribuito.
Installazione: comandi, non racconti
La sezione di installazione è quella che si legge con più attenzione e si sbaglia più spesso. Alcune regole:
- Comandi completi in blocchi di codice, pronti da copiare. Niente «installate le dipendenze» senza dire come.
- Un comando per riga e nell'ordine giusto.
- Indicare dove eseguire il comando: «dalla cartella del progetto», «come amministratore».
- Mostrare come verificare che l'installazione sia riuscita.
git clone <indirizzo-del-repository>
cd rinomina-scansioni
python -m venv .venv
source .venv/bin/activate # su Windows: .venv\Scripts\activate
pip install -r requirements.txt
python rinomina.py --versione # deve mostrare il numero di versione
Uso: prima l'esempio, poi le opzioni
Le persone imparano dagli esempi. Mettete per primo il caso più frequente, con un input e il risultato atteso:
python rinomina.py ~/Scansioni/oggi
# 2026-10-14_prot-0457.pdf
# 2026-10-14_prot-0458.pdf
Solo dopo, l'elenco completo delle opzioni. Per elenchi lunghi una tabella è più leggibile:
| Opzione | Effetto | Predefinito |
|---|---|---|
--prova |
Mostra i nuovi nomi senza rinominare | disattivo |
--formato |
Schema del nome del file | {data}_prot-{numero} |
--ricorsivo |
Elabora anche le sottocartelle | disattivo |
Configurazione e segreti
Se il progetto richiede chiavi di accesso, password o indirizzi di server, il README deve spiegare dove metterli senza mai contenerli. Il modo più pulito è fornire un file di esempio, come config.example.yaml o .env.example, con valori fittizi, e indicare di copiarlo con il nome reale, escluso dal controllo di versione.
Problemi noti
Questa sezione nasce dalle domande ricevute. Ogni volta che qualcuno chiede aiuto per lo stesso problema, la risposta va nel README:
- Sintomo: il messaggio di errore esatto, così è trovabile con una ricerca.
- Causa: una frase.
- Soluzione: il comando o l'impostazione da cambiare.
Stile di scrittura
- Frasi brevi, all'imperativo nelle istruzioni: «Eseguite», «Copiate», «Aprite».
- Niente gergo non spiegato; se un termine è necessario, una definizione in una riga.
- Titoli con
##coerenti, così le piattaforme generano un indice navigabile. - Aggiornamento insieme al codice: un README che descrive una versione vecchia è peggio di un README breve.
Nel mio lavoro, prima di considerare finito uno strumento, provo a installarlo seguendo solo il README su una macchina pulita. Ogni passaggio in cui devo «ricordare» qualcosa è una riga mancante.
In sintesi
- Le prime righe dicono nome, funzione concreta e destinatari.
- Installazione con comandi completi, in ordine, con un modo per verificare il risultato.
- Nell'uso viene prima l'esempio più comune, poi l'elenco delle opzioni.
- I segreti non vanno mai nel README: si fornisce un file di configurazione di esempio.
- I problemi ricorrenti diventano una sezione, e il README si aggiorna insieme al codice.
