Come scrivere un README

di Lorenzo Neri

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.

Continua a scoprire di più con questi articoli!

Lascia un commento

Questo sito potrebbe fare uso di cookie e siccome l'UE mi obbliga a fartelo presente, eccoti il classico banner dove puoi decidere come gestirli. Accetta Leggi di più