Le lettere maiuscole si distinguono e rendono il file facilmente visibile, il che ha senso perché è probabilmente la prima cosa che un nuovo utente vorrebbe vedere. (O almeno, dovrebbe aver guardato ...) Come altri hanno già detto, i nomi dei file che iniziano con una lettera maiuscola saranno elencati prima dei nomi in minuscolo in ASCIIbetical ordinamento ( LC_COLLATE=C
) che aiuta a rendere il file visibile a prima vista.
Il file README
fa parte di un gruppo di file che un utente di un pacchetto software libero normalmente si aspetterebbe di trovare. Altri sono INSTALL
(istruzioni per la creazione e l'installazione del software), AUTHORS
(elenco dei contributori), COPYING
(testo della licenza), HACKING
(come iniziare per contribuire, forse includendo un elenco TODO di inizio punti), NEWS
(modifiche recenti) o ChangeLog
(principalmente ridondante con i sistemi di controllo della versione).
Questo è ciò che i Norme di codifica GNU hanno per dire sul file README
.
The distribution should contain a file named README
with a general overview of the package:
- the name of the package;
- the version number of the package, or refer to where in the package the version can be found;
- a general description of what the package does;
- a reference to the file
INSTALL
, which should in turn contain an explanation of the installation procedure;
- a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
- a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called
COPYING
. If the GNU LGPL is used, it should be in a file called COPYING.LESSER
.
Poiché è sempre bene cercare la minima sorpresa dei tuoi utenti, dovresti seguire questa convenzione a meno che non ci siano motivi validi per una deviazione. Nel mondo UNIX, le estensioni dei nomi di file venivano tradizionalmente usate con parsimonia, quindi il nome canonico del file è README
senza suffisso. Ma la maggior parte degli utenti probabilmente non avrebbe problemi a capire che un file chiamato README.txt
ha lo stesso significato. Se il file è scritto in Markdown , potrebbe anche essere ragionevole un nome di file come README.md
. Evita di utilizzare linguaggi di markup più complessi come HTML nel file README
, tuttavia, perché dovrebbe essere conveniente leggere su un terminale di solo testo. Puoi indirizzare gli utenti al manuale del software o alla sua documentazione online, che potrebbe essere scritta in un formato più sofisticato, per i dettagli del file README
.