Ao abrir um repositório no GitHub, a primeira coisa que aparece abaixo da lista de arquivos é o README. Se ele estiver vazio ou confuso, muita gente desiste sem olhar o código. Se estiver claro, o projeto ganha usuários, colaboradores e credibilidade, inclusive em portfólios.
O que é o README
O nome é um aviso antigo: leia-me. É um arquivo de texto na raiz do projeto, normalmente chamado README.md, onde a extensão indica o formato Markdown. Se você ainda não conhece, o guia de Markdown para anotações cobre a sintaxe básica. Se estiver começando com repositórios, veja Git e GitHub para iniciantes.
O que incluir
Pense em quem chega sem contexto e quer saber três coisas: o que é, se serve para mim e como começo.
- Nome e descrição curta: uma ou duas frases dizendo o que o projeto faz e para quem.
- Demonstração: captura de tela, GIF ou link do projeto no ar, se houver.
- Requisitos: versões de linguagem, banco de dados ou ferramentas necessárias.
- Instalação: os comandos em ordem, para copiar e colar.
- Como usar: um exemplo mínimo que funcione.
- Configuração: variáveis de ambiente necessárias, sem expor valores reais. Se precisar de ajuda com isso, veja variáveis de ambiente e arquivo .env.
- Como contribuir: regras simples para sugerir mudanças, se você aceita colaboração.
- Licença: informe sob qual licença o código é distribuído. Sem licença, outras pessoas não têm clareza sobre o que podem fazer com ele. Em caso de dúvida sobre qual escolher, consulte a documentação do GitHub ou um profissional.
Estrutura simples
Uma organização que serve para a maioria dos projetos usa títulos de segundo nível em Markdown, como Sobre, Requisitos, Instalação, Uso, Contribuição e Licença. Blocos de código devem mostrar os comandos exatamente como serão digitados.
Erros comuns
- Começar pela história do projeto em vez de dizer o que ele faz.
- Deixar comandos desatualizados depois de mudanças no código.
- Esquecer requisitos, como a versão do Node ou do Python, e fazer o usuário descobrir pelo erro.
- Colocar senhas, chaves de API ou dados pessoais em exemplos. Use valores falsos e deixe claro que são exemplos.
- Escrever um README enorme que ninguém lê. Prefira o essencial e links para documentação mais longa.
- Esquecer de atualizar o arquivo quando o projeto muda de rumo.
Um README não precisa ser bonito para ser útil. Precisa ser verdadeiro, direto e testado. Quando o projeto crescer, você pode adicionar um histórico de mudanças e uma seção de problemas conhecidos.