thecodest, Autore presso The Codest

Dovrebbe contenere tutti gli aspetti che lo sviluppatore ha bisogno di conoscere e che non possono essere ricevuti direttamente dall'azienda. codice. Questi includono le regole e le regole di sviluppo, le istruzioni complete per la distribuzione, le descrizioni delle integrazioni esterne e così via. Questo post vi guiderà nella creazione di un file README potente, bello e leggibile per il vostro progetto.

Una bella introduzione per una documentazione di progetto ben preparata si trova nelle guide di github: https://guides.github.com/features/wikis/. Questo afferma che "il README dovrebbe contenere solo le informazioni necessarie agli sviluppatori per iniziare a usare e contribuire al progetto".

A questo proposito, presentiamo un elenco di componenti e di buone pratiche che seguiamo in Codest per creare la documentazione di un progetto.

Introduzione rapida

- Titolo del progetto: questo è un must per ogni README.

- Badge di statoSe si utilizzano misurazioni esterne della qualità del codice, test automatici o altri strumenti, l'inizio del documento è un buon posto per mostrare agli altri se funzionano.

- Descrizione: includere alcune frasi sul progetto per descrivere rapidamente lo scopo principale e ciò che fa.

Indice dei contenuti

Un elenco dei contenuti può essere utile per i file di documentazione lunghi, ma se il vostro README è abbastanza conciso non è necessario.

Informazioni generali

- Informazioni sulla sezione: si tratta di una descrizione più dettagliata del progetto, che può includere informazioni sugli utenti, sui loro ruoli, su alcuni casi più confusi, su schermate, ecc.

- Mockup: un posto per i link alle risorse di mockup UI/UX, se ce ne sono.

Altre informazioni come Accesso ai server o Integrazione con API esterneEsempi: l'indirizzo dell'istanza di staging, le credenziali di accesso non sensibili (!) condivise, i link alla documentazione, alcune istruzioni, ecc.

Installazione

- Requisiti: prerequisiti che devono essere soddisfatti prima di avviare la configurazione di un'applicazione, ad esempio l'installazione di strumenti esterni.

- Impostazione: un'istruzione passo-passo da seguire per avviare il progetto.

- Impostazionidescrivono dove vengono memorizzate le impostazioni locali e forniscono istruzioni su come ricevere le proprie impostazioni.

- Configurazione localeSe ci sono casi di configurazione locale, questo è un buon posto per una spiegazione.

Sviluppo

Questa sezione è il luogo ideale per istruzioni come lo sviluppo di funzionalità, bugfix, hotfix, funzionalità comuni, test, guide di stile, organizzazione del codice, altri strumenti di sviluppo utilizzati nel progetto (ad esempio, guardie o docker) e così via. Non dimenticatevi di menzionare tutte le regole che ogni squadra membro dovrebbe sapere.

Distribuzione

Fornire chiare istruzioni passo-passo per ogni ambiente e tutto ciò che è "bene sapere" durante la distribuzione.

Altre idee per le sezioni separate

- Documentazione API

- Changelog

- Risorse esterne: un luogo per tutti i tipi di link che possono essere utili.

- Pila di applicazioni: un elenco dello stack applicativo utilizzato nel progetto - può contenere una breve descrizione e il nome del fornitore.

Squadra

È discutibile se sia necessario mostrare i membri attuali del team del progetto (github fornisce l'elenco completo dei collaboratori per impostazione predefinita), ma è sempre bello vedere il proprio nome come uno degli autori di un progetto. Se lo fate, tenetelo il più aggiornato possibile.

Le ultime parole

Ricordate: ogni progetto è unico e così la sua documentazione. Non esiste un'unica soluzione per scrivere un README. Basta seguire i consigli generali e la cosa più importante è ricordare sempre il refactoring, che si collega anche al README. È sempre una buona idea guardare il documento nel suo complesso e ripensarlo se qualcosa deve essere visualizzato in modo diverso.

Un'altra cosa: le "istruzioni" sono fondamentali, quindi scrivetele spesso. Grazie!

Per saperne di più: