Come scrivere un README? Come funziona? In questo articolo scopriamo tutto questo e per quale motivo è così importante.
Non solo: scopriremo anche COSA è necessario scrivere per renderlo efficace e di facile utilizzo.
Ciao mi chiamo Lorenzo Neri e sono un informatico: realizzo contenuti per aiutare le persone a padroneggiare l’arte del nuovo millennio, ovvero l’informatica!
Prima ancora di addentrarci a capire come si scrive e come funziona un file README, è necessario capire che cosa è un file README.
Che cos’è un file README?
Un file README, è in termini poco tecnichesi un file di testo.
Un file di testo che contiene informazioni essenziali e al contempo estese che permette di capire di che cosa tratta, come funziona e come utilizzare il progetto per cui è stato scritto.
Se stai cercando lavoro nel mondo dell’informatica, stessa cosa vale se stai studiando e vorresti arrotondare, è un ottimo asso nella manica.
Il motivo? Semplice: se hai dei progetti, ad esempio su GitHub e desideri renderli pubblici, i tuoi lettori capiranno subito che cosa hanno davanti a sé.
Tuttavia, non è un puro e semplice file di testo.
Un file README, è sì un file di testo, ma scritto in MarkDown.
Il MarkDown, è un modo molto pratico, semplice ed immediato per scrivere testo sul web: ma con stile!
No, non lo stile che pensi tu! Ci permette di scrivere del testo, ma formattato con tanto di elementi grafici.
Chiarito questo, immagino tu abbia già capito che ci sono delle regole ben precise per scriverlo, così come l’estensione di questi file è “md” che sta appunto per “MarkDown”.
Ciò detto, vediamo appunto come si scrivere un README.
Come scrivere un README: la sintassi
Il primo passo che muoviamo per capire come si scrive un README è chiaramente la sintassi.
Una volta creato il tuo file, che deve avere estensione “.md”, partiamo da ciò che è il titolo.
Il titolo
Per scrivere un titolo in formato MarkDown, è sufficiente fare come segue:
# Titolo
E il risultato ottenuto sarà questo:
Possiamo inserire titoli anche più piccoli, ovvero degli header
Gli Header
Per gli header, è sufficiente aggiungere ulteriori cancelletti: più ne si mettono, più piccolo diventerà, per esempio:
## Header1
### Header2
#### Header 3
Ed eccoli qui:
Ma giustamente c’è un altro punto da chiarire
Il testo!
Per scrivere il testo semplice all’interno di un README, ti è sufficiente scriverlo senza particolari simboli.
Invece parliamo di cose più interessanti.
Il codice
Per scrivere il codice, cosa importante all’interno di un README, è necessario usare i backslash (`) con il linguaggio di programmazione desiderato.
Per esempio:
```python
from time import sleep
print("Sono del codice Python")
```
```javascript
var informatico="ciao sono JavaScript";
console.log(informatico);
```
Et voilà:
In sintesi, la sintassi per aggiungere codice ben formattato al tuo README è come segue:
```LinguaggioDiProgrammazione
codice
codice
codice
```
Altra cosa essenziale sono i collegamenti.
I collegamenti
Per farli, è necessario specificare il testo del collegamento e il link ovvero il collegamento stesso:
[Blog di Lorenzo](https://lorenzoneri.com)
E il risultato eccolo qua:
Arrivati a questo punto che abbiamo capito la sintassi necessaria per scrivere un README, ma dobbiamo capire un altro punto essenziale e importantissimo.
Come scrivere un README utile, buono ed efficace
Certo sapere la sintassi per scriverlo bene è ottimo, ma bisogna capire COSA scrivere per renderlo davvero utile ed efficace per chi lo leggerà.
Nome
Scegli un nome che basti a far capire il progetto stesso.
Descrizione
Spiega nel dettaglio e nello specifico cosa fa il tuo progetto. Offri un contesto di uso ma soprattutto aggiungi i link necessari a far capire ai tuoi visitatori meno familiari di cosa si sta parlando.
Per esempio una lista di feature oppure un background.
Badge
Diversi README hanno delle immagini che contengono metadati. Per esempio se tutti o solo alcuni informatico passano: per questo puoi usare Shields.
Installazione
Questo è importantissimo.
Considera di esplicitare tutte le dipendenze, tutti i pacchetti necessari, i sistemi operativi su cui funziona il tuo progetto, insomma: l’essenziale e il necessario per poterlo utilizzare.
Al contempo anche dove non si può utilizzare: considera di aggiungere una sezione “Requisiti”.
Utilizzo
Spiega brevemente con degli esempi e relativo output come si utilizza.
Supporto
Spiega ai tuoi utenti dove ti possono trovare.
Contributi
Specifica se sei disposto a contributi da parte di esterni.
Autori
Ovviamente, a parte te stesso se ci sono altri autori citali.
Stato del progetto
Questo è importantissimo. Hai presente quando trovi un progetto e magari scopri per vie traverse che non è più seguito?
Ecco: se pensi di non avere più tempo per tenerlo in piedi scrivilo tramite aggiornamenti.
Licenze
Concludo, tra i vari punti per come si dovrebbe scrivere un README che le licenze vanno messe.
