La mia applicazione è pensata per essere utilizzata da normali utenti di tutti i giorni, ma può anche essere modificata liberamente dagli sviluppatori. Questi due segmenti di pubblico (utenti e sviluppatori) richiedono informazioni diverse.
Il mio README dovrebbe mirare agli utenti o è più appropriato indirizzare il README verso gli sviluppatori?
Un file "readme" è semplicemente "cosa leggere prima". Chi sei non significa niente: apri prima il readme.
Da lì devi indirizzare gli utenti alla documentazione corretta:
Avere collegamenti a una documentazione più appropriata. README è semplicemente un punto di partenza. Spiegare dove trovare la documentazione di installazione. Spiegare dove trovare la documentazione per gli sviluppatori. Documentazione di utilizzo Changelog. README dovrebbe essere un segnavia: l'unico posto in cui guardare per essere diretto a dove devi davvero andare.
Molti software hanno LEGGIMI HTML con navigazione e simili, spesso inclusi nel software o nel codice sorgente. Ciò è positivo perché la formattazione e i collegamenti ipertestuali sono più utili del testo normale. Il tuo semplice file di testo README potrebbe indirizzare qualcuno verso un documento più espressivo.
Forse hanno collegamenti a GitHub o ovunque il software sia disponibile, che generalmente ha anche più documentazione. La documentazione di GitHub è più strettamente legata alla struttura del codice, poiché i suoi file di markdown risiedono nelle cartelle di origine. Questo sarebbe un ottimo posto per mettere la documentazione per gli sviluppatori.
Qualunque sia la documentazione, avere collegamenti ai documenti per "Voglio solo installare, cosa devo fare?" e "come compilare da zero su piattaforme supportate".
Infine, la documentazione per gli sviluppatori è ben posizionata nei documentats Doxygen, JavaDoc o GitHub. Questi sono formati di documentazione standard che gli sviluppatori dovrebbero sapere come costruire e leggere. Essendo utenti più tecnici, gli sviluppatori richiedono meno mani. Fornisci una soluzione makefile, Ant script o Visual Studio e dovrebbero essere in grado di capirlo.
Come accennato a Robert Harvey nel suo commento, non esiste una cosa standard da fare. Fai ciò che ha senso per il tuo software e il suo pubblico previsto, ma fornisci informazioni utili a prescindere. Se lasci dei breadcrumb nel tuo README, dovresti stare bene: il suo scopo è quello di essere un cartello.
"Sviluppatore" eredita da "utente". Se è buono per gli utenti, probabilmente andrà bene per gli sviluppatori. È vero, gli utenti non leggono spesso la documentazione. Ma se hai 100 utenti per ogni sviluppatore e anche l'1% degli utenti legge README e, ad esempio, il 50% degli sviluppatori li legge, avrai ancora il doppio degli utenti che guardano il README rispetto agli sviluppatori. Quindi prendi entrambi.
Sia gli utenti non sviluppatori che gli sviluppatori vorranno sapere due cose per cominciare:
A quel punto, avranno altre domande come
Ma le risposte che si aspettano potrebbero essere molto diverse (potrebbero sperare risposte a domande come "quale pulsante devo premere?" vs "quale file sorgente devo modificare?"). Questo è quando si scomporre in documenti diversi. Indica innanzitutto le esercitazioni per tutti e poi collega alla documentazione per gli sviluppatori.
Leggi altre domande sui tag documentation