Readme: panoramica sugli elementi principali, incluso template

Readme, già il nome è un invito: “leggimi”’. Infatti, il file readme è il primo file che lo sviluppatore dovrebbe visionare prima di iniziare un progetto. Allo stesso modo è importante che gli sviluppatori sappiano scrivere un buon file readme per riprodurre in modo conciso tutte le informazioni rilevanti.

Cos’è un file readme e a cosa serve?

Un file readme, creato spesso come readme.txt o readme.md, contiene di solito informazioni importanti su un sistema, un progetto o un software. Per permettere agli utenti di visualizzare subito il file, la sua posizione ideale è in cima alla directory.

Consiglio

Spesso README viene scritto tutto maiuscolo nel nome file. I sistemi che distinguono tra maiuscole e minuscole lo posizioneranno prima di tutti i file che iniziano con la lettera minuscola.

Il file ha scopi diversi a seconda del tipo di utente:

  • nel caso di un utente finale, il file readme chiarisce possibili dubbi relativi all’installazione, all’aggiornamento e all’utilizzo di un software;
  • per gli sviluppatori del progetto stesso, il file readme offre due vantaggi. Da un lato, un file readme scritto prima di avviare l’attività di sviluppo fornisce una linea guida per la creazione del progetto. Dall’altro facilita una ripresa più rapida se un progetto è messo in pausa per un periodo di tempo più lungo;
  • per gli altri sviluppatori il file readme chiarisce il codice e fornisce indicazioni importanti per lo sviluppo successivo o l’applicazione di un sistema, di un software o di progetti open source.

Cosa dovrebbe contenere un file readme?

A seconda dello scopo, un file readme può presentare i seguenti contenuti:

  • una descrizione generale del sistema o progetto;
  • lo stato del progetto, importante soprattutto quando quest’ultimo si trova ancora nella fase di sviluppo. Nel file sono indicate le modifiche previste e la direzione dello sviluppo, o se un progetto è stato completamente sviluppato;
  • i requisiti dell’ambiente di sviluppo per l’integrazione,
  • istruzioni d’installazione e uso;
  • un elenco delle tecnologie utilizzate ed eventualmente dei link per ulteriori informazioni a riguardo;
  • i progetti open source, che gli sviluppatori modificano o ampliano in maniera indipendente, dovrebbero contenere in readme.md una parte per la “collaborazione desiderata”. Com’è possibile eludere i problemi? Qual è il miglio modo per gli sviluppatori di implementare eventuali modifiche?
  • bug noti ed eventuali debug;
  • area FAQ con tutte le domande già poste in precedenza;
  • informazioni su copyright e licenze.

Quando si scrive un file readme, è importante che questo sia pensato per l’utente finale e che provi a chiarire la maggior parte delle possibili domande.

Formati file possibili per un file readme

Un file readme può essere scritto e salvato in qualsiasi formato per file di testo. I formati vanno da readme.txt, readme.doc fino a readme.s1t. Il formato del file readme viene adeguato al relativo sistema e programma di testo in base della piattaforma su cui dovrà girare il software. Il questo modo si avrà la certezza che il programma di testo possa leggere il file.

Attualmente gli sviluppatori usano prevalentemente il formato readme.md. Cos'è un file .md? L’estensione rimanda ad un file readme in formato markdown. Markdown trasforma il testo in HTML tramite semplici caratteri di formattazione. Un file readme ben formattato e strutturato consente all’utente di avere una panoramica completa del progetto.

Readme.md: un esempio in formato markdown

Vi mostriamo come si realizza un file read.me, passo dopo passo, e quali sono le possibili formattazioni in markdown. Per consentire una cooperazione globale ed evitare barriere linguistiche, dovreste scrivere il file readme sempre in lingua inglese.

Un esempio di readme in formato markdown:

# Project name
***
Short Description about the project.
Consiglio

Con “***” inserite una linea di separazione orizzontale.

Al primo posto di un file readme troviamo un nome progetto eloquente e una breve spiegazione del tipo di progetto. In markdown un cancelletto “#” indica sempre un titolo. Il numero di cancelletti definisce i tipi di titolo:

# Headline H1
## Headline H2
### Headline H3
#### Headline H4 
##### Headline H5
###### Headline H6

Nel caso di una documentazione estesa, un indice chiaro fornisce una buona visione d’insieme:

## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)

L’indice di readme.md può essere ben strutturato tramite un elenco ordinato. Per creare l’elenco basta semplicemente inserire il numero corrispondente a inizio riga.

GitHub inserisce automaticamente degli ID ai titoli nel file readme. Gli ID vengono generati dai nomi dei titoli e i trattini “-” sostituiscono gli spazi. Sono perfetti per essere utilizzati nella navigazione anchor dell’indice. Se il file readme.md è pensato per una piattaforma che non fornisce i titoli direttamente con degli ID, la navigazione anchor viene realizzata con HTML:

## Table of Contents
<a name="general-info"></a>
### General Info

L’indice viene seguito da ciascun blocco di contenuto per i singoli punti:

## General Info
***
Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. 
### Screenshot
![Image text](/path/to/the/screenshot.png)

Una breve spiegazione riguardo alle informazioni generali sul progetto è importante per avere una panoramica generale. Con markdown è possibile inserire nella documentazione anche grafici, screenshot o altre immagini. Per farlo, basta scrivere un termine che li descriva tra parentesi quadre, seguito dall’URL all’immagine tra parentesi tonde (senza spazi vuoti nel mezzo). Inserire prima un punto esclamativo così il markdown lo interpreterà come file immagine.

## Technologies
***
A list of technologies used within the project:
* [Technology name](https://example.com): Version 12.3 
* [Technology name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234

Nel formato markdown i punti di un elenco numerato si creano anteponendo una “*” a inizio riga.

I link possono essere inseriti nella posizione preferita in readme.md. La struttura è molto simile a quella di un formato immagine, ma senza punto esclamativo a inizio riga. La parola per la quale creare il link va scritta tra parentesi quadre, seguita dal percorso per il sito web tra parentesi tonde (anche in questo caso senza spazi vuoti nel mezzo).

N.B.

Il file dovrebbe trovarsi sempre nella stessa repository. Potete utilizzare anche altri file open source disponibili. C’è però il rischio che il proprietario di questi file li cancelli da un momento all’altro facendo scomparire il vostro readme.md.

## Installation
***
A little intro about the installation.
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start

Visto che un file readme viene utilizzato spesso nell’ambito dello sviluppo software, è utile inserire esempi di testo sorgente nel documento. Anche in questo caso, Markdown ha un’opzione per la formattazione. Il codice può essere formattato con “```” all’inizio e alla fine. È possibile utilizzare parti di codice anche direttamente nel testo. 

## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part. 
> It should go over several rows?
> This is how you do it.

Un “>” a inizio riga trasforma il testo in una citazione. 

## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer of the first question with _italic words_. 
2. __Second question in bold__ 
To answer this question we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer of the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |

Gli elenchi ordinati e non ordinati possono essere utilizzati anche in combinazione in readme.md. A tal fine bisogna proseguire l’elenco numerato con il numero corrispondente.

A scopo esemplificativo abbiamo inserito qui termini o segmenti di testo in corsivo e in grassetto. Il corsivo si ottiene digitando un semplice asterisco “*” o un underscore “_” prima o dopo il rispettivo termine o segmento di testo. Per il grassetto bisogna utilizzare un doppio asterisco o un doppio underscore.

Anche le tabelle possono essere inserite in readme.md grazie al formato markdown e si realizzano con barre verticali “|” e trattini “-”. I due punti stabiliscono se orientare il testo a sinistra, a destra o al centro.

Esempio di template readme

Qui di seguito ritroverete tutti gli esempi fatti finora, raggruppati e riassunti come template readme.

## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)
### General Info
***
Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. 
### Screenshot
![Image text](https://www.united-internet.de/fileadmin/user_upload/Brands/Downloads/Logo_IONOS_by.jpg)
## Technologies
***
A list of technologies used within the project:
* [Technologie name](https://example.com): Version 12.3 
* [Technologie name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234
## Installation
***
A little intro about the installation.
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start
## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part. 
> It should go over several rows?
> This is how you do it.
## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer of the first question with _italic words_. 
2. __Second question in bold__ 
To answer this question we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer of the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |
Consiglio

L’editor WYSIWYG -di Dillinger permette di realizzare online un readme.md in modo rapido e semplice.

Hai trovato questo articolo utile?
Per offrirti una migliore esperienza di navigazione online questo sito web usa dei cookie, propri e di terze parti. Continuando a navigare sul sito acconsenti all’utilizzo dei cookie. Scopri di più sull’uso dei cookie e sulla possibilità di modificarne le impostazioni o negare il consenso.