Articolo originale: https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/
Quando sono stato introdotto a GitHub, non avevo idea di cosa fosse o cosa potesse fare. Detto tra noi, ho creato l'account perché mi era stato detto che tutti gli sviluppatori ne dovrebbero avere uno sul quale pubblicare il proprio codice.
Per la maggior parte del tempo da principiante non ho fatto nulla col mio account. Ma poi, grazie alla mia passione per tecnologia, ho iniziato a seguire altri sviluppatori e leggere i loro lavori su GitHub. E ho notato una cosa che avevano in comune: avevano tutti progetti interessanti e contribuivano a progetti open source, ma i loro progetti avevano anche dei file README dettagliati.
Quindi il mio interesse in cosa fosse un README era cresciuto, e ho deciso di provare ad aggiungerne uno ai miei progetti. Non mentirò - l'ho fatto di corsa senza alcuna idea su come dovesse essere fatto. E onestamente il risultato non era granché. Guarda tu stesso.
Ed è rimasto così per un periodo di tempo. Ma grazie alla pratica e all'apprendimento continuo ho imparato a realizzare migliori documentazioni come QUESTA, il che ha migliorato la partecipazione con i progetti e ha aiutato altri sviluppatori a unirsi.
É anche importante sapere che un buon README ti aiuterà a farti notare in mezzo alla moltitudine di sviluppatori che pubblicano il loro lavoro su GitHub.
In questo articolo, impareremo cos'é un file README e come scriverne uno. Prima di tutto capiamo cosa si intende per "file README".
Cos'é un file README?
In parole povere, possiamo definire un file README come una guida che dà a un utente una descrizione dettagliata di un progetto sul quale hai lavorato.
Può essere anche descritto come una documentazione con linee guida su come usare un progetto. Di solito contiene istruzioni su come installare ed eseguire un progetto.
É essenziale per te come sviluppatore sapere come documentare il tuo progetto scrivendo un README perché:
- É il primo file che una persona vedrà aprendo il tuo progetto, quindi dovrebbe essere piuttosto sintetico ma dettagliato.
- Farà spiccare il tuo progetto tra gli altri. Ma assicurati che il progetto sia buono.
- Ti aiuterà a definire cosa deve offrire il tuo progetto e come.
- Migliorerà le tue abilità di scrittura, come disse Friedrich Nietzsche:
Un bravo scrittore non possiede solamente il suo spirito, ma anche lo spirito dei suoi amici.
Mentre lavori a un progetto, tieni a mente che dovrai far capire cosa fa il tuo codice anche ad altri sviluppatori. Quindi affiancargli una guida sarà decisamente utile.
Ad esempio, il mio primo progetto mostrato in precedenza, non ha un buon README. E anche se il progetto era fantastico, sarebbe stato difficile per un principiante capire esattamente cosa aspettarsi quando avrebbero clonato il mio repo. Per lui sarebbe anche potuto essere un virus.
Con un progetto del genere su GitHub, non importa quanto sia ben fatto, gli altri sviluppatori non saranno disposti a capirlo e a lavorarci senza un buon README.
Ora, dai un'occhiata a questo progetto. Qui, sei in grado di capire cosa fa il progetto, cosa prevede e come iniziare se hai bisogno di usare o contribuire al progetto.
Vedi, ecco quanto può essere utile un README ben strutturato e come può cambiare il tuo progetto.
Quindi, iniziamo a vedere come puoi scriverne uno.
Come scrivere un buon README - una guida passo passo
Una cosa importante da sapere è che non c'è un modo migliore per strutturare un buon README. Ma c'è un modo sbagliatissimo, ed è non scriverlo affatto.
Studiando vari file README, naturalmente ho delle buone pratiche. E sono proprio queste che condividerò. Come dico sempre:
Ogni giorno è un giorno in cui imparare.
Quindi andando avanti e progredendo nella tua carriera, svilupperai le tue idee su cosa rende ben strutturato un README e come migliorarlo. Magari un giorno scriverai una tua guida originale.
Prima di iniziare, è anche importante sapere che, quando scrivi il tuo README, dovresti essere in grado di rispondere al cosa, al perché, e al come del progetto.
Ecco qualche domanda che ti aiuterà:
- Qual è la tua motivazione?
- Perché hai creato questo progetto?
- Quale problema risolve?
- Cosa hai imparato?
- Cosa lo differenzia dagli altri?
Se il tuo progetto ha molte funzionalità, considera l'aggiunta di una sezione "Features" nella quale elencarle.
Cosa includere nel tuo README
1. Titolo del progetto
Questo è il nome del progetto. Descrive tutto il progetto in una frase e aiuta le persone a capire qual è l'obiettivo, ovvero a cosa punta il progetto.
2. Descrizione del progetto
Questa è una componente importante del progetto che molti sviluppatori inesperti tendono a sottovalutare.
La descrizione è un aspetto estremamente importante del tuo progetto. Una descrizione ben fatta ti permette di mostrare il tuo lavoro ad altri sviluppatori e a potenziali datori di lavoro.
La qualità di un buona descrizione è spesso la differenza tra un buon progetto ed un progetto carente. Uno buon README sfrutta la possibilità per spiegare e mostrare:
- Cosa fa la tua applicazione,
- Perché hai utilizzato determinate tecnologie,
- Alcune delle difficoltà che hai affrontato e le funzionalità che speri di aggiungere in futuro.
3. Indice (facoltativo)
Se il tuo README è molto lungo, forse è il caso di aggiungere un indice per rendere più semplice la navigazione tra le sezioni.
4. Come installare ed eseguire il progetto
Se stai lavorando su un progetto che l'utente deve installare o eseguire in locale in una macchina come un "POS", dovresti includere i passaggi per installare il tuo progetto ed anche le dipendenze, se ci sono.
Metti a disposizione una descrizione passo passo di come creare ed eseguire l'ambiente di sviluppo.
5. Come usare il progetto
Fornisci istruzioni ed esempi a utenti e collaboratori. Semplificherà loro la vita quando avranno un problema - avranno sempre un posto dove trovare cosa aspettarsi.
Puoi anche usare supporti visivi includendo materiale come screenshot per mostrare esempi del progetto in esecuzione o per mostrare la struttura e i principi di design usati nel tuo progetto.
Se il tuo progetto richiede autenticazioni come password e username, questa è una buona sezione nella quale includere le credenziali.
6. Includi i ringraziamenti/riferimenti
Se hai lavorato su un progetto con un team o un'organizzazione, elenca i tuoi collaboratori/compagni di squadra. Dovresti anche includere un link al loro profilo GitHub e/o ai loro social media.
Inoltre, se hai seguito tutorial o fatto riferimento ad alcuni materiali che potrebbero aiutare l'utente a costruire un particolare progetto, includi i link.
Questo è uno dei modi ringraziare ed aiutare gli altri a mettere mano su progetti simili.
7. Aggiungi una licenza
Per la maggior parte dei file README, questo è solitamente considerata la parte finale. Permette agli altri sviluppatori di sapere cosa possono e non possono fare con il tuo progetto.
Esistono tipi di licenza diversi a seconda del tipo di progetto sul quale stai lavorando. A seconda di quella che sceglierai riceverai diversi tipi di contributi.
La più comune è la Licenza GPL che permette agli altri di modificare il tuo codice ed usarlo a scopi commerciali. Se hai bisogno di aiuto nello scegliere una licenza, dai un'occhiata a questo sito: https://choosealicense.com/ (risorsa in lingua originale inglese).
Fino a questo punto abbiamo soddisfatto i requisiti minimi per un buon README. Ma potresti anche voler considerare di aggiungere le seguenti sezioni per renderlo più interattivo e accattivante.
Sezioni README aggiuntive
8. Badge
I badge non sono necessari, ma usarli è un modo semplice di far sapere agli altri sviluppatori che sai cosa stai facendo.
Avere questa sezione potrebbe anche essere utile per aiutare a linkare i tool più importanti e mostrare qualche statistica riguardante il tuo progetto come il numero di fork, collaboratori, issue aperte ecc.
Ecco uno screenshot di uno dei miei progetti che mostra come poter utilizzare i badge:
Un lato positivo di questa sezione è che si aggiorna automaticamente.
Non sai da dove iniziare? Dai un'occhiata ai badge di shields.io. Hanno un sacco di badge che possono aiutarti a iniziare. Potresti non capirli tutti, ma piano piano inizierai a riuscirci.
9. Come contribuire al progetto
Questo sarà utile soprattutto se stai sviluppando un progetto open-source nel quale avrai bisogno del contributo di altri sviluppatori. Dovrai aggiungere delle linee guida per far sapere loro come contribuire al tuo progetto.
É importante anche assicurarsi che la licenza che scegli per un progetto open-source sia corretta per evitare conflitti futuri. E l'aggiunta di linee guida ai contributi giocherà un ruolo importante.
Alcune delle linee guida più comuni includono il codice di comportamento del collaboratore e la guida alla contribuzione. Queste documentazioni ti daranno il supporto che ti serve quando imposterai le regole del tuo progetto.
10. Includi i test
Vai oltre e scrivi dei test per la tua applicazione. Dopodiché, fornisci esempi di codice e il modo per eseguirli.
Questo aiuterà a mostrare che sei certo e convinto che il tuo codice funzionerà senza difficoltà, il che darà fiducia anche agli altri.
Punti extra
Ecco un altro paio di punti dei quali tenere conto mentre scrivi il tuo README:
- Mantienilo aggiornato - è una buona pratica assicurarsi che il tuo file sia aggiornato. In caso ci fossero modifiche assicurati di aggiornare il README se necessario.
- Scegli una lingua - Veniamo tutti da diversi luoghi e parliamo lingue diverse. Ma questo non significa che tu debba tradurre il tuo codice in dialetto. Scrivere il tuo codice in inglese basta e avanza. Potresti aggiungere un sistema di traduzione in caso la tua audience non conoscesse l'inglese.
Conclusione
Ecco tutto ciò di cui hai bisogno per migliorare i tuoi file README, o addirittura iniziare a scrivere il primo.
A questo punto sono sicuro che tu sia nella posizione di aggiungere una guida interattiva ed informativa al tuo prossimo progetto o a uno già esistente in modo da farlo spiccare.
Ci sono molti strumenti che puoi usare per generare automaticamente un README, ma sarebbe meglio provare a farne qualcuno per conto tuo prima di passare ad automatizzare il processo. Nel caso volessi provarne qualcuno:
Grazie per essere arrivato fino a qui. Se ti è piaciuto questo articolo, per favore condividilo in modo da aiutare altri sviluppatori a migliorare i loro progetti.
Mi piacerebbe vedere il tuo file README appena realizzato. Condividi il link attraverso uno dei seguenti canali:
Connettiti con me: Twitter | YouTube | LinkedIn | GitHub
Condividi la tua opinione, apprezzo i feedback costruttivi!
Buona programmazione ❤