Readme: pa­no­ra­mi­ca sugli elementi prin­ci­pa­li, incluso template

Readme, già il nome è un invito: “leggimi”’. Infatti, il file readme è il primo file che lo svi­lup­pa­to­re dovrebbe visionare prima di iniziare un progetto. Allo stesso modo è im­por­tan­te che gli svi­lup­pa­to­ri sappiano scrivere un buon file readme per ri­pro­dur­re in modo conciso tutte le in­for­ma­zio­ni rilevanti.

Un file readme, creato spesso come readme.txt o readme.md, contiene di solito in­for­ma­zio­ni im­por­tan­ti su un sistema, un progetto o un software. Per per­met­te­re agli utenti di vi­sua­liz­za­re subito il file, la sua posizione ideale è in cima alla directory.

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’in­stal­la­zio­ne, all’ag­gior­na­men­to e all’utilizzo di un software;
• per gli svi­lup­pa­to­ri 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 svi­lup­pa­to­ri il file readme chiarisce il codice e fornisce in­di­ca­zio­ni im­por­tan­ti per lo sviluppo suc­ces­si­vo o l’ap­pli­ca­zio­ne di un sistema, di un software o di progetti open source.

A seconda dello scopo, un file readme può pre­sen­ta­re i seguenti contenuti:

• una de­scri­zio­ne generale del sistema o progetto;
• lo stato del progetto, im­por­tan­te so­prat­tut­to 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 com­ple­ta­men­te svi­lup­pa­to;
• i requisiti dell’ambiente di sviluppo per l’in­te­gra­zio­ne,
• istru­zio­ni d’in­stal­la­zio­ne e uso;
• un elenco delle tec­no­lo­gie uti­liz­za­te ed even­tual­men­te dei link per ulteriori in­for­ma­zio­ni a riguardo;
• i progetti open source, che gli svi­lup­pa­to­ri mo­di­fi­ca­no o ampliano in maniera in­di­pen­den­te, do­vreb­be­ro contenere in readme.md una parte per la “col­la­bo­ra­zio­ne de­si­de­ra­ta”. Com’è possibile eludere i problemi? Qual è il miglio modo per gli svi­lup­pa­to­ri di im­ple­men­ta­re eventuali modifiche?
• bug noti ed eventuali debug;
• area FAQ con tutte le domande già poste in pre­ce­den­za;
• in­for­ma­zio­ni su copyright e licenze.

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

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 piat­ta­for­ma su cui dovrà girare il software. Il questo modo si avrà la certezza che il programma di testo possa leggere il file.

At­tual­men­te gli svi­lup­pa­to­ri usano pre­va­len­te­men­te il formato readme.md. Cos'è un file .md? L’esten­sio­ne rimanda ad un file readme in formato markdown. Markdown trasforma il testo in HTML tramite semplici caratteri di for­mat­ta­zio­ne. Un file readme ben for­mat­ta­to e strut­tu­ra­to consente all’utente di avere una pa­no­ra­mi­ca completa del progetto.

Vi mostriamo come si realizza un file read.me, passo dopo passo, e quali sono le possibili for­mat­ta­zio­ni in markdown. Per con­sen­ti­re una coo­pe­ra­zio­ne globale ed evitare barriere lin­gui­sti­che, dovreste scrivere il file readme sempre in lingua inglese.

Un esempio di readme in formato markdown:

Al primo posto di un file readme troviamo un nome progetto eloquente e una breve spie­ga­zio­ne del tipo di progetto. In markdown un can­cel­let­to “#” indica sempre un titolo. Il numero di can­cel­let­ti definisce i tipi di titolo:

Nel caso di una do­cu­men­ta­zio­ne estesa, un indice chiaro fornisce una buona visione d’insieme:

L’indice di readme.md può essere ben strut­tu­ra­to tramite un elenco ordinato. Per creare l’elenco basta sem­pli­ce­men­te inserire il numero cor­ri­spon­den­te a inizio riga.

GitHub inserisce au­to­ma­ti­ca­men­te degli ID ai titoli nel file readme. Gli ID vengono generati dai nomi dei titoli e i trattini “-” so­sti­tui­sco­no gli spazi. Sono perfetti per essere uti­liz­za­ti nella na­vi­ga­zio­ne anchor dell’indice. Se il file readme.md è pensato per una piat­ta­for­ma che non fornisce i titoli di­ret­ta­men­te con degli ID, la na­vi­ga­zio­ne anchor viene rea­liz­za­ta con HTML:

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

Una breve spie­ga­zio­ne riguardo alle in­for­ma­zio­ni generali sul progetto è im­por­tan­te per avere una pa­no­ra­mi­ca generale. Con markdown è possibile inserire nella do­cu­men­ta­zio­ne anche grafici, screen­shot 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 escla­ma­ti­vo così il markdown lo in­ter­pre­te­rà come file immagine.

Nel formato markdown i punti di un elenco numerato si creano an­te­po­nen­do 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 escla­ma­ti­vo 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).

Visto che un file readme viene uti­liz­za­to spesso nell’ambito dello sviluppo software, è utile inserire esempi di testo sorgente nel documento. Anche in questo caso, Markdown ha un’opzione per la for­mat­ta­zio­ne. Il codice può essere for­mat­ta­to con “```” all’inizio e alla fine. È possibile uti­liz­za­re parti di codice anche di­ret­ta­men­te nel testo.

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

Gli elenchi ordinati e non ordinati possono essere uti­liz­za­ti anche in com­bi­na­zio­ne in readme.md. A tal fine bisogna pro­se­gui­re l’elenco numerato con il numero cor­ri­spon­den­te.

A scopo esem­pli­fi­ca­ti­vo abbiamo inserito qui termini o segmenti di testo in corsivo e in grassetto. Il corsivo si ottiene digitando un semplice asterisco “*” o un un­der­sco­re “_” prima o dopo il ri­spet­ti­vo termine o segmento di testo. Per il grassetto bisogna uti­liz­za­re un doppio asterisco o un doppio un­der­sco­re.

Anche le tabelle possono essere inserite in readme.md grazie al formato markdown e si rea­liz­za­no con barre verticali “|” e trattini “-”. I due punti sta­bi­li­sco­no se orientare il testo a sinistra, a destra o al centro.

Qui di seguito ri­tro­ve­re­te tutti gli esempi fatti finora, rag­grup­pa­ti e riassunti come template readme.