Resposta rápida: o que faz um bom README de projeto?
Um bom README de projeto no GitHub permite entender o resultado, executar o projeto e decidir o que fazer depois. Comece com um resumo em linguagem simples e mostre o caminho mais curto até o primeiro sucesso: requisitos, instalação, exemplo mínimo e resultado esperado. Depois acrescente configuração, estrutura, contribuição, licença e limitações.
A intenção de como escrever um bom README para seu projeto no GitHub é diferente da de um Profile README pessoal. O README do repositório documenta software, dados, sites, pacotes ou experimentos. Para apresentar uma pessoa, consulte o guia de modelos de Profile README. Esta página fica focada no onboarding e na manutenção do projeto.
Não faça o leitor adivinhar o runtime, a pasta de trabalho ou o ponto de entrada da demo. Um README.md curto e correto é mais útil que uma página bonita que não leva do clone ao primeiro resultado.
Imagens e widgets são evidências de apoio. Screenshot, diagrama, GIF curto ou badge de teste podem complementar uma explicação. Para a sintaxe e manutenção de badges, veja o guia de badges para README; para atividade, consulte o guia do gráfico de contribuições do GitHub.
Seções de README que merecem espaço
Use a tabela como um modelo de README para projeto no GitHub. Nem todo repositório precisa de todas as seções, mas a primeira pessoa deve encontrar objetivo, primeira execução e próximo link sem procurar em vários parágrafos.
Organize as seções pelo trabalho do leitor. Uma aplicação web com demo pode mostrar a demo cedo; uma biblioteca precisa de instalação e exemplo de API; uma ferramenta interna precisa explicar variáveis de ambiente e limites de acesso.
| Seção | Objetivo | Manter | Evitar |
|---|---|---|---|
| Resumo do projeto | Dizer o que o repositório faz e para quem. | Resultado concreto, escopo e status. | Slogan sem caso de uso. |
| Funções e demo | Mostrar o que o visitante pode ver ou usar. | Lista curta, demo, saída ou screenshot. | Prometer função que a branch atual não oferece. |
| Requisitos | Evitar surpresas no setup. | Runtime, sistema, dependências e versões suportadas. | Presumir que todos conhecem sua toolchain. |
| Instalação | Levar do clone a um ambiente funcional. | Comandos na ordem correta e pasta de trabalho. | Comandos antigos copiados de uma issue. |
| Uso e configuração | Explicar o caminho principal e as opções. | Exemplo mínimo, entradas, saídas e variáveis. | Referência longa antes do primeiro resultado. |
| Estrutura do projeto | Ajudar a navegar pelo repositório. | Arquivos úteis para usuários e colaboradores. | Listar todo arquivo gerado. |
| Contribuição | Definir expectativas para issues e pull requests. | Testes, formatação, branches e verificações locais. | Pedir contribuições sem explicar como verificar. |
| Licença e limitações | Deixar claros o reuso e os limites. | Licença, limitações, dados e notas de segurança. | Sugerir garantias que o projeto não oferece. |
Um fluxo de escrita em cinco passos
Escreva o README a partir da primeira tarefa do leitor, não da ordem em que o código foi construído. O fluxo serve para um repositório novo ou para uma atualização após uma release. Escreva o texto primeiro; coloque imagens e badges depois que o caminho principal estiver correto.
O README também é parte da manutenção. Quando um comando, branch, variável, screenshot ou URL da demo mudar, revise a documentação no mesmo pull request.
Defina leitor e resultado
Decida se a primeira pessoa é usuária, colaboradora, revisora, estudante ou avaliadora. Diga o que ela deve conseguir em cinco minutos.
Desenhe o caminho mais curto
Escreva resumo, requisitos, instalação, exemplo mínimo e saída esperada. Se isso estiver confuso, deixe a decoração para depois.
Adicione provas e contexto
Inclua funções, demo, screenshot, saída, arquitetura ou testes para avaliar o repositório sem ler todos os arquivos.
Documente configuração e contribuição
Explique variáveis, opções, estrutura, verificações locais, issues, licença e limitações conhecidas.
Execute o README como teste
Faça um clone limpo, siga os comandos, abra links e imagens e revise a página no celular antes do merge.
Exemplos por tipo de projeto
O melhor README para mostrar um projeto nem sempre é o mais longo. Ajuste as provas e os passos ao que o repositório realmente entrega. Uma CLI deve parecer rápida; uma aplicação web precisa de demo e ambiente; uma biblioteca precisa de um exemplo de API copiável.
Use os exemplos como padrões de decisão, não como texto genérico. Comandos, provas e limitações devem vir do repositório real.
CLI ou automação
Mostre o problema, instalação, entrada e saída, opções, códigos de saída e uma forma segura de testar localmente.
Aplicação web ou dashboard
Coloque demo ou screenshot no começo, liste runtime e variáveis, explique o start local e os dados de exemplo.
Biblioteca ou pacote
Coloque o comando de instalação e o menor exemplo de import no alto. Acrescente runtime, API, versões e breaking changes.
Dados ou pesquisa
Documente a fonte, preparação, saídas, limites de reprodução, licença e como inspecionar o resultado.
Projeto open source
Deixe visíveis setup local, testes, formatação, labels de issues, código de conduta e decisões de design.
Como usar imagens, badges e demos
Uma imagem deve responder a uma pergunta que o texto responderia lentamente. Use screenshot para a interface, diagrama para arquitetura, exemplo de saída para arquivos gerados e alt text descritivo junto à seção explicativa.
Badges são metadados opcionais, não substitutos de documentação. Uma linha pequena pode mostrar build, versão, licença ou coverage quando a fonte é verificável e atual. O guia de badges para README explica padrões Markdown estáveis; remova badges antigos.
Visualizações de atividade dão contexto, mas não provam que um repositório é útil. Se você adicionar gráfico, cartão de estatísticas ou visual 3D, explique o que ele mede e deixe comportamento, testes e exemplos como evidências principais.
Regra simples
Se um visual não ajuda a entender, executar, avaliar ou confiar no projeto, mova-o para baixo ou remova-o. A conclusão deve estar no HTML, não apenas na imagem.
Verificações antes de publicar o README
Trate o README como um pequeno artefato de release. Um teste a partir de um clone limpo encontra mais problemas que uma revisão final de ortografia.
| Problema | Causa provável | Correção |
|---|---|---|
| O primeiro comando falha | Runtime, pasta, branch ou variável não documentados. | Execute o quick start em um clone limpo e atualize requisitos e ordem dos comandos. |
| O resultado não fica claro | Há comandos, mas não há saída esperada ou sinal de sucesso. | Mostre uma saída, screenshot, URL, resultado de teste ou caminho de arquivo. |
| Demo ou imagem quebrada | Branch renomeada, asset privado, caminho relativo errado ou deploy removido. | Abra todos os links e recursos na página renderizada e use caminhos estáveis. |
| A configuração é um mistério | As variáveis de ambiente aparecem somente no código. | Liste valores, exemplos seguros, padrões e tratamento de segredos. |
| Contribuições não podem ser verificadas | Não há comandos de test, lint, format ou build. | Adicione as verificações locais esperadas antes de um pull request. |
| README difícil no celular | Imagens grandes, tabelas largas ou muitos badges. | Comprima mídia, reduza tabelas e teste em uma viewport pequena. |
| As promessas excedem o projeto | Texto de marketing antigo ou copiado de roadmap. | Ligue cada função a uma demo, comando, teste ou limitação atual. |
FAQ sobre READMEs de projetos GitHub
O que colocar no começo do README?
Nome, resultado em uma frase, status atual e o link ou comando mais rápido para ver o projeto funcionando. O contexto longo vem depois do quick start.
Um push cria um README?
Não. O GitHub pode inicializar um repositório com README, mas enviar um projeto local não escreve a documentação. Adicione README.md manualmente.
Preciso mostrar toda a estrutura de pastas?
Mostre apenas pastas e arquivos úteis para navegar. Uma árvore curta e comentada é melhor que uma lista gerada que muda a cada build.
Posso usar gerador ou prompt?
Sim para criar um esqueleto, mas confirme comandos, caminhos, dependências, funções, imagens e licença no repositório real. Texto gerado não é prova.
Onde colocar badges?
Uma pequena linha atualizada pode ficar perto do título ou status. Ela não deve empurrar instalação e uso para fora da área inicial.
Como manter o README atualizado?
Revise com releases e pull requests, teste o quick start periodicamente, remova links antigos e mantenha versões, variáveis e URLs da demo.