As letras maiúsculas se destacam e tornam o arquivo facilmente visível, o que faz sentido, porque é provavelmente a primeira coisa que um novo usuário gostaria de ver. (Ou, pelo menos, deveria ter olhado para…) Como já foi dito, os nomes de arquivos iniciados com uma letra maiúscula serão listados antes dos nomes em minúsculas na classificação ASCIIbetics ( LC_COLLATE=C
), o que ajuda a tornar o arquivo visível à primeira vista.
O README
arquivo faz parte de vários arquivos que um usuário de um pacote de software livre normalmente esperaria encontrar. Outras são INSTALL
(instruções para compilar e instalar o software), AUTHORS
(lista de colaboradores), COPYING
(texto da licença), HACKING
(como começar a contribuir, talvez incluindo uma lista TODO de pontos de partida), NEWS
(alterações recentes) ou ChangeLog
(principalmente redundantes com sistemas de controle de versão).
É o que os Padrões de Codificação GNU têm a dizer sobre o README
arquivo.
A distribuição deve conter um arquivo nomeado README
com uma visão geral do pacote:
- o nome do pacote;
- o número da versão do pacote ou consulte onde o pacote pode ser encontrado;
- uma descrição geral do que o pacote faz;
- uma referência ao arquivo
INSTALL
, que por sua vez deve conter uma explicação do procedimento de instalação;
- uma breve explicação de qualquer diretório ou arquivo incomum de nível superior ou outras dicas para os leitores encontrarem o caminho da fonte;
- uma referência ao arquivo que contém as condições de cópia. A GNU GPL, se usada, deve estar em um arquivo chamado
COPYING
. Se o GNU LGPL for usado, ele deverá estar em um arquivo chamado COPYING.LESSER
.
Como é sempre bom procurar a menor surpresa de seus usuários, você deve seguir esta convenção, a menos que haja razões convincentes para um desvio. No mundo UNIX, as extensões de nome de arquivo eram tradicionalmente usadas com moderação, de modo que o nome canônico do arquivo não possui README
sufixo. Mas a maioria dos usuários provavelmente não teria problemas para entender que um arquivo chamado README.txt
tem o mesmo significado. Se o arquivo estiver escrito no Markdown , um nome de arquivo como README.md
também pode ser razoável. Evite usar linguagens de marcação mais complicadas, como HTML, noREADME
arquivo, no entanto, porque deve ser conveniente ler em um terminal somente de texto. Você pode indicar aos usuários o manual do software ou a documentação on-line, que pode ser escrita em um formato mais sofisticado, para obter detalhes do README
arquivo.