Un README utile: spiegare il primo risultato, non tutto il progetto
Di Redazione Quaderno dei Sistemi
Organizza un README con scopo, prerequisiti, primo utilizzo e limiti. Una struttura concreta per chi apre un progetto senza conoscerlo.
Un README dovrebbe aiutare una persona nuova a capire che cosa fa il progetto e come ottenere un primo risultato verificabile. Non deve necessariamente contenere l’intero manuale. GitHub lo presenta come un punto di orientamento del repository: il nostro suggerimento è costruirlo attorno alla prima operazione utile.
Scrivere per chi arriva oggi
Apri con due frasi: quale problema viene affrontato e a chi serve il progetto. Evita formule come «soluzione completa» se non specifichi completa rispetto a cosa. Indica poi i prerequisiti effettivi, distinguendo quelli indispensabili da quelli facoltativi. Una versione del sistema operativo non verificata non va trasformata in compatibilità garantita.
Un esempio con risultato atteso
Descrivi una piccola operazione e ciò che dovrebbe apparire alla fine. Per un convertitore di file, ad esempio, nomina il file di ingresso, il comando previsto e il nome dell’uscita. Non inserire credenziali reali o dati personali nell’esempio. Se il comando dipende da una configurazione, spiega dove impostarla prima di eseguirlo.
Spostare il resto nel posto giusto
Dopo il primo utilizzo, collega istruzioni approfondite, problemi noti e modalità di segnalazione. Un indice breve aiuta più di un documento iniziale enorme. Alla revisione, chiedi a una persona che non ha seguito il lavoro di individuare il primo passo senza spiegazioni a voce.
Concludi con i limiti conosciuti. Non sono un difetto da nascondere: evitano che un lettore attribuisca al progetto capacità mai dichiarate o verificate.