O README é parte fundamental de qualquer projeto, independente do tamanho da equipe. É uma ótima ferramenta de documentação e deve estar presente até em projetos privados.

Quando o projeto é privado, os membros da equipe dependem, muitas vezes, de informações que não estão disponíveis no Google, informações privadas e exclusivas do projeto. Essas informações, e muitas outras, devem ser documentadas de alguma maneira, para uso posterior por outros membros da equipe e até mesmo pelo cliente.

Todo projeto deve incluir um README entre seus arquivos, seja ele .txt (não, plz!) ou .md, e deve, preferencialmente, ser escrito em inglês.

Como escrever o README

Para mim, todo README deve conter, no mínimo, os seguintes itens:

  1. Informações sobre o projeto
  2. Badges
  3. Dependências
  4. Instruções de instalação
  5. Instruções de uso
  6. Instruções de como testar
  7. Informações extra

Informações sobre o projeto

Todo README deve começar apresentando informações básicas sobre o projeto, como nome e descrição. Essas informações são úteis para os novatos e, principalmente, no momento da manutenção do sistema (meses ou até anos após o desenvolvimento).

Seja breve e claro ao descrever o sistema, ninguém gosta de enrolação e muito texto irá assustar qualquer um que abrir seu README.

Badges

CodeClimate, CodeShip, Travis, Coverall, etc. Todos esses serviços oferecem pequenas badges que podem ser adicionadas ao README. Além de colorir, essas badges tonarão informações úteis acessíveis para todos os envolvidos no projeto.

Dependências

Liste todas as dependências do projeto no README. É fácil esquecer de algo, você saberá disso, sempre que um novo companheiro de equipe se juntar ao projeto. Evite problemas e perda de tempo listando todas as dependências necessárias no README. Uma lista simples é suficiente, só não esqueça de informar as versões.

Em alguns casos, pode ser interessante anexar links para tutoriais ou dicas de como resolver problemas comuns ou, até mesmo, instalar todas as dependências.

Instruções de instalação

Certamente, não há melhor lugar para esse tipo de informação. Mais uma vez, seja claro e direto, enrolação só complica. Divida o processo de instalação em passos (1, 2, 3...) e lembre-se de listar todos os comandos executados.

Nem sempre todos os envolvidos no projeto possuem o mesmo conhecimento técnico que o seu, por isso, é necessário utilizar uma linguagem simples. Use links externos com detalhes sobre conceitos "obscuros", se for necessário.

Instruções de uso

Sim, o seu README deve explicar como utilizar o sistema. Seja sucinto e foque no que realmente importa. Você só precisa apresentar as peculiaridades do sistema.

Mostre como inicializar serviços, comandos úteis, urls importantes, contas padrão, qualquer coisa que não pareça tão obvio.

Instruções de como testar

Nem sempre as coisas são tão simples como parecem, por isso, seu README deve conter informações de como preparar o ambiente de testes e executá-los.

Informações extra

Adicione ao README qualquer informação extra que achar pertinente e útil, para você ou outros membros da equipe. Inclua links e postagens úteis, convenções do projeto e dicas.

Finalizando

O README é uma importante ferramenta de comunicação e documentação do projeto. Gaste um tempo para organizar-lo e incentive contribuições dos outros membros da equipe, afinal, todos irão consultá-lo.

Boa sorte!