Un README dovrebbe aiutare un nuovo lettore a fare la prima mossa utile. Non è necessario spiegare ogni dettaglio dell'implementazione prima che possano dire cosa fa il progetto o se è rilevante per loro.

Guida con il risultato

Descrivi cosa fa il progetto, a chi è rivolto e i suoi limiti importanti. Un esempio concreto è più utile di un elenco di aggettivi. Inserisci uno screenshot funzionante o un risultato di esempio nella parte superiore quando aiuta a spiegare lo scopo.

Successivamente indicare i prerequisiti: sistema operativo, versione runtime e servizi richiesti. Distinguere le integrazioni facoltative da quelle necessarie per iniziare. Non lasciare che il lettore scopra un requisito essenziale a metà dell'installazione.

Fornisci un percorso completo verso il successo

Scrivi i passaggi di configurazione nell'ordine in cui devono essere eseguiti. Spiegare dove dovrebbero essere eseguiti i comandi e come si presenta un risultato positivo. Utilizza la configurazione dei segnaposto in modo chiaro e non includere mai credenziali reali nell'esempio.

Prova le istruzioni da un checkout pulito o da un punto di partenza equivalente. Un comando che funziona solo perché sul tuo computer è installato uno strumento non documentato è una lacuna nella documentazione. Mantieni le variazioni facoltative al di sotto del percorso supportato più semplice.

Rendi il passaggio successivo facile da trovare

Aggiungi i comandi comuni per eseguire, controllare e aggiornare il progetto. Collegati a una documentazione più approfondita invece di inserire ogni argomento specialistico nella sezione di apertura. Includere il luogo supportato in cui segnalare problemi e la licenza, ove pertinente.

Utilizza MeatPad per modificare il file README accanto ai file di progetto, quindi controlla il rendering Markdown nella destinazione. Segui i collegamenti e ispeziona le immagini con i percorsi effettivi del repository. Quando la configurazione cambia, aggiorna il README nella stessa modifica in modo che le istruzioni di prima esecuzione descrivano la versione che le persone riceveranno.

Fonti e dettagli del prodotto

Inizia con una nota. MeatPad fornisce alle note, Markdown e ai file di progetto uno spazio di lavoro locale sul tuo Mac, senza la necessità di un account.

Esplora MeatPad →