README "Impostazione" sezione best practice?

In generale

Se si fa riferimento a prodotti ben documentati, la soluzione più sicura sarebbe quella di fornire un collegamento alle istruzioni originali così come è stato fatto: queste dovrebbero sempre essere aggiornate e affrontare i numerosi problemi specifici della piattaforma.

Questa politica è la stessa del codice e delle librerie: se una libreria fornisce una funzione o una classe, dovresti generalmente usarla così com'è e non riscrivere la tua su misura.

Ma ...

Ma il mondo non è perfetto. Quindi ci sono almeno 3 eccezioni a questa politica:

• il componente originale non è ben documentato (ad esempio documenti obsoleti o fuorvianti)
• il repository originale non è stabile (ad esempio frequente cambio di url della documentazione o url specifico della versione): il tuo link potrebbe rompersi rapidamente
• il tuo codice dipende profondamente da un componente complesso e offri garanzie per i tuoi utenti solo per un insieme specifico di versioni (e questo è il motivo per cui versioning semantico questioni).

Esiste un'altra eccezione, ma pragmatica: se le istruzioni sono davvero banali (ad esempio installa un pacchetto o scarica il programma di installazione e segui le istruzioni) potresti anche fornire direttamente le istruzioni. Gli utenti apprezzeranno, in quanto non dovranno sfogliare i kilobyte di documentazione solo per trovare istruzioni così banali.

Onestamente questo è il punto in cui molta opinione e politica entrerà in gioco. Tuttavia l'obiettivo è lo stesso. Le istruzioni di installazione dovrebbero contenere abbastanza informazioni che ogni idiota può configurare il progetto. Questo è importante, perché non sono solo le persone che sono abituate alla catena di strumenti che avranno bisogno di configurare il progetto. Ci sarà, in un punto casuale nel futuro, qualcuno che non ha idea di cosa stia facendo, ma ha un certo controllo sul budget, che vorranno "dare un'occhiata".

Quindi di solito ho fissato questi obiettivi.

1. Utilizza gli strumenti per configurare il progetto dove mai possibile. Ad esempio, invece di una lista di gemme usa semplicemente rake.
2. Assicurati che l'installazione sia "un passo". Ad esempio rake setup . Quindi aggiungi le parti a quello. Quindi installa bundle, rake db: migrate, cosa fare-cosa è, qualunque cosa. Questo non è sempre possibile in quanto significa che il rastrello deve funzionare, quindi hai un pollo e un uovo.
3. Risolvi pollo e uova con le istruzioni per fare un pollo. Ad esempio, "È necessario disporre di un ambiente di lavoro sano per configurare questo progetto, vedere (collegamento al sito Web qui) per le istruzioni su come installare (ambiente di lavoro qui). Ora è importante mantenere questo" pollo "il più semplice possibile. Quindi, nell'esempio Ruby, le istruzioni per impostare ruby, rubygems, rake, quindi consegnare il processo per impostare il rake.

La ragione per cui i link sono cattivi è la stessa ragione per cui non ci sono problemi con Stackexchange. Non saranno sempre lì. Tuttavia questo è meno di un problema, perché è possibile modificare il read me (e dovrebbe essere) di frequente. Quindi se qualcuno dice che le "istruzioni per installare ruby" non funzionano, puoi semplicemente sostituire il link.

La ragione per cui i grandi blocchi di testo sono cattivi è perché non c'è proprio bisogno. Il 90% del tuo "pubblico" non guarderà mai il read me. Specialmente se hai rake setup attivo. Poi sai come impostare rubino, gemme di rubini e rastrello e non hanno bisogno delle tue istruzioni per farlo. Ciò di cui potrebbe aver bisogno è una rapida lista di dipendenze dispari. E per questo, una lista con link alle istruzioni è ottima.