Come scrivere un file README TXT: una guida informale da qualcuno che c’è già passato

Onestamente, creare un file README TXT ben strutturato può sembrare un po’ noioso e banale, ma fidatevi, è fondamentale se avete intenzione di condividere il vostro set di dati o progetto con altri. Mi è capitato di trovarmi in quella situazione in cui avevo dati grezzi, nessuna spiegazione e nessuna idea di cosa fosse, e questo non faceva che creare confusione in seguito. Ecco quindi un modo semplice per creare un file README decente: niente di complicato, solo informazioni sufficienti affinché qualcun altro (o il vostro futuro “te”) possa capire di cosa si tratta.

Apertura dell’editor di testo: avvio del tutto

Per prima cosa, prendi l’editor di testo normale che ti è più congeniale. Su Windows, Blocco Note funziona, ma se sei un po’ più esperto, forse Notepad++, o semplicemente semplificati la vita: TextEdit su Mac in modalità testo normale. Linux? Probabilmente gedit, nano o qualsiasi altra cosa sia nella tua distribuzione. Onestamente, ho usato anche vim, il che è un po’ eccessivo se sei alle prime armi. Comunque, aprilo; tutto quello che fai qui è scrivere informazioni di base, senza bisogno di formattazione o RTF. Solo testo normale. Salvalo con nome, README.txtindicando chiaramente dove si trova. Se hai una cartella dedicata al tuo progetto, salva lì il README insieme ai tuoi file di dati. Usa File > Salva con nome, seleziona Testo normale (*.txt). Facile.

Assegnare un nome al file README: come chiamarlo?

In alto, inserisci il nome del tuo set di dati o progetto: non è solo un segnaposto; è l’ancora che rende tutto più chiaro. Ad esempio, invece di chiamarlo semplicemente “README”, sii più specifico: Climate_Data_2024.txt. In questo modo, quando scorri una cartella in un secondo momento, non ti confondi. Potrebbe sembrare banale, ma ti fa risparmiare un sacco di tempo mentale. Consideralo come un modo per etichettare la tua cassetta degli attrezzi, in modo da non dover estrarre dati a caso quando ti servono effettivamente i dati meteorologici.

Elenco di chi ha creato questo e di eventuali link DOI

Ora, includi un elenco degli autori o del tuo team. Magari solo il tuo nome se si tratta di un progetto individuale. Se è presente un DOI, ovvero un Digital Object Identifier, una sorta di collegamento permanente ai dati o alla pubblicazione, aggiungilo. Di solito puoi ottenerlo da repository come Zenodo, DataCite o persino GitHub. Ad esempio: https://doi.org/xx/xxxxx. Includere un DOI rende il tuo set di dati facile da citare e aggiunge credibilità, soprattutto se altri lo riutilizzeranno. Se non sei sicuro se dovresti farlo, pensa semplicemente: “Qualcuno vorrà convalidarlo o citarlo in seguito?”.In caso affermativo, inserisci quel DOI. E come best practice, mantienilo semplice ma completo: nessuno vuole indovinare chi l’ha messo insieme o da dove proviene.

Aggiunta delle date di creazione e ultimo aggiornamento

Dopodiché, annota quando hai creato il file README e quando lo hai aggiornato l’ultima volta. Puoi digitare la data manualmente, ad esempio 25/04/2024, oppure, se preferisci, usare gli strumenti da riga di comando per generarla. Ad esempio, su Mac/Linux, il datecomando, o su Windows PowerShell, Get-Date. Ma onestamente, digitarla funziona benissimo. Queste informazioni sono davvero utili, soprattutto se aggiorni dataset o documentazione nel tempo.È utile anche specificare se è disponibile una versione più recente di eventuali file correlati, in modo che gli utenti sappiano di stare consultando le informazioni più recenti. Se il tuo dataset verrà aggiornato regolarmente, valuta la possibilità di aggiungere un numero di versione come v1.0 o una nota di “ultimo aggiornamento” per chiarezza. Non è una cosa complicata, ma aiuta a evitare confusione in seguito.

Documentazione di variabili, termini o colonne di dati

Ecco dove finalmente sono entrato nei dettagli: elenca tutte le variabili, le caratteristiche o i termini chiave nei dati. Sii estremamente descrittivo. Ad esempio, se il tuo set di dati registra le temperature, specifica se si tratta di gradi Celsius o Fahrenheit, come Temperatura (°C). Lo stesso vale per altre misurazioni: pressione, umidità, livelli di pH, qualsiasi cosa. Se non sei sicuro del significato di un termine o delle unità di misura utilizzate, contrassegnalo con un punto interrogativo, come Livello di pH [?]. In questo modo, i futuri utenti o persino tu stesso in seguito saprai che devi ricontrollarlo. Inoltre, se i tuoi dati utilizzano sistemi di coordinate o sistemi di riferimento specifici, come WGS84 per i dati geografici, aggiungi queste informazioni. Punti bonus se includi un rapido esempio per ogni variabile, in modo che sia chiaro che tipo di valori aspettarsi.

---

Tutto sommato, seguire questo tipo di modello generico rende il tuo README più di una semplice pagina vuota.È una rapida mappa per chiunque (incluso, onestamente, il tuo futuro io) per capire cosa contiene e come è stato creato. Lo ammetto, mi ci sono voluti un po’ di tentativi per capire quanti dettagli aggiungere e dove inserire la data dell’ultimo aggiornamento senza sovraccaricarlo. Ma armeggiare anche con un semplice file di testo è meglio che lasciare tutto senza documentazione, fidatevi.

Spero che questo vi sia stato utile: ci ho messo davvero troppo tempo a capire tutto. Buona fortuna e buona documentazione! Se non altro, almeno è meglio di quel vago “README” che ho ignorato per settimane.

---

---