Como documentar projetos no GitHub: o README que importa

Você abre um repositório promissor, lê o nome, lê uma frase vaga e... fecha a aba. Faltou o básico: o que isso faz, para quem serve e como eu rodo. O README é a porta de entrada do projeto e, na prática, quase sempre a única documentação que alguém vai ler de verdade. Se ele não responde essas três perguntas nos primeiros segundos, todo o esforço que você colocou no código fica invisível. Este texto é sobre como documentar projetos no GitHub de um jeito que respeite o tempo de quem chega depois — incluindo você mesmo daqui a seis meses.

O foco aqui é o conjunto mínimo que importa: o README bem estruturado, os arquivos de apoio (CONTRIBUTING, LICENSE, templates de issue e PR, changelog), quando partir para uma wiki ou um site de docs, e por que registrar o "porquê" das decisões vale tanto quanto explicar o "como".

O que um bom README responde nos primeiros segundos

Antes de qualquer seção bonita, o leitor precisa de três respostas imediatas: o que o projeto faz, para quem ele é e como rodar. Se a pessoa precisa rolar a página ou clonar o repo para descobrir o propósito, o README já falhou. A primeira linha logo abaixo do título deve ser uma frase única e concreta — não "uma solução moderna e robusta", mas "CLI que converte planilhas CSV em relatórios PDF".

O público também importa. Uma biblioteca para outros desenvolvedores integrarem é diferente de uma ferramenta de linha de comando para usuário final, e o README precisa deixar claro logo de cara qual dos dois é. Quando o "para quem" está implícito, metade dos leitores erra a expectativa e abandona.

A estrutura que funciona

Depois de anos lendo e escrevendo READMEs, a estrutura que sobrevive ao contato com a realidade é quase sempre a mesma:

• Título + uma linha do que o projeto é.
• Badges de build, versão, cobertura e licença — sinais rápidos de saúde do projeto.
• Instalação com o comando exato, sem pressupor ambiente.
• Uso com pelo menos um exemplo real que roda.
• Configuração das variáveis e opções principais.
• Contribuição apontando para o CONTRIBUTING.
• Licença explícita.

Montar essa estrutura na mão, com os badges no formato certo e as seções na ordem que o leitor espera, consome um tempo bobo. Para um esqueleto inicial consistente, um gerador de README resolve a parte mecânica e te deixa focar no conteúdo que só você sabe escrever.

O exemplo de uso é a seção mais negligenciada e a mais importante. Um trecho que a pessoa copia, cola e vê funcionando vale mais que três parágrafos descrevendo o que o projeto "permite fazer". Algo assim já muda o jogo:

# instala
npm install csv-to-pdf

# converte um arquivo
csv-to-pdf relatorio.csv -o relatorio.pdf --template fatura

Repare que o exemplo tem entrada real, flag real e saída esperada. Não é pseudocódigo. Quem leu já sabe que a ferramenta funciona e como ela se parece em uso.

Além do README: os arquivos de apoio

O README carrega o peso, mas alguns arquivos complementares mudam a postura do projeto de "código jogado no ar" para "projeto que aceita gente". O CONTRIBUTING.md explica como rodar os testes, qual o padrão de commit e o que você espera de um PR — sem ele, cada contribuição vem em um formato diferente. O LICENSE não é detalhe burocrático: sem licença explícita, legalmente ninguém pode usar seu código com segurança.

Os templates de issue e PR economizam ida e volta. Um template de bug que pede versão, passos para reproduzir e comportamento esperado evita aquele "não funciona" sem contexto. O changelog (idealmente seguindo Keep a Changelog) deixa claro o que mudou entre versões, o que é ouro para quem vai atualizar uma dependência.

A regra prática: comece pelo README e pelo LICENSE. Adicione CONTRIBUTING e templates quando o projeto começar a receber gente de fora. Não crie arquivos vazios só para ter — um CONTRIBUTING com uma linha genérica é pior que nenhum.

Quando partir para wiki ou site de docs

Enquanto a documentação cabe em uma página rolável, ela deve ficar no README. A tentação de espalhar tudo numa wiki cedo demais costuma terminar em páginas mortas que ninguém atualiza. O sinal de que chegou a hora de migrar é concreto: o README passou de algumas telas, tem várias seções longas concorrendo por atenção, ou você precisa de tutoriais passo a passo, referência de API e guias separados.

Aí faz sentido um site de docs (MkDocs, Docusaurus, VitePress) com o README virando uma landing enxuta que aponta para lá. A wiki do GitHub funciona para projetos pequenos com notas soltas, mas some do controle de versão do código — então mudanças de doc não aparecem no mesmo PR que muda o comportamento. Para projeto sério, prefira docs versionadas junto do código.

Documente o "porquê", não só o "como"

A documentação que mais envelhece bem é a que registra decisões. Seis meses depois, ninguém lembra por que vocês escolheram fila em vez de chamada síncrona, ou por que aquela dependência estranha está ali. ADRs (Architecture Decision Records) — arquivos curtos em docs/adr/ descrevendo contexto, decisão e consequências — resolvem isso. Não precisa de cerimônia: um parágrafo por decisão já evita meses de arqueologia de Git.

O "como" muda toda hora; o "porquê" é o que dá continuidade ao projeto. Quando alguém entende a razão de uma escolha, consegue revisá-la com critério em vez de quebrar tudo por desconhecimento. Documentar a intenção é o que separa um projeto que pessoas conseguem manter de um que só o autor original entende — a mesma lógica de quando você organiza um portfólio de desenvolvedor: contar a decisão importa tanto quanto mostrar o resultado.

Perguntas frequentes

Qual o tamanho ideal de um README?

Grande o suficiente para responder o que faz, para quem e como rodar, com um exemplo real — e nada além disso. Na maioria dos projetos, isso cabe em uma a três telas de rolagem. Quando passa muito disso, é sinal de que partes deveriam virar páginas separadas num site de docs.

Preciso de badges no README?

Badges de build, versão e licença ajudam porque comunicam saúde do projeto em um relance, antes mesmo de ler texto. Mas badge decorativo que não diz nada só polui o topo. Coloque os que carregam informação real e remova o resto.

README ou wiki: qual usar?

Comece sempre pelo README. Migre para wiki ou site de docs quando o conteúdo crescer a ponto de precisar de navegação, tutoriais e referência separados. Prefira docs versionadas junto do código a wikis que vivem fora do controle de versão.

Como manter a documentação atualizada?

Trate doc como parte do PR: mudou comportamento, mudou a doc no mesmo commit. Doc desatualizada é pior que doc ausente, porque mente para quem confia nela. Revisões periódicas curtas, a cada release, evitam o acúmulo silencioso de mentiras.

O que levar daqui

Escreva o README pensando em você mesmo daqui a seis meses, sem o contexto fresco que você tem agora. Comece pelas três perguntas — o que faz, para quem, como rodar — garanta um exemplo de uso que realmente roda, e só depois adicione os arquivos de apoio conforme o projeto cresce. Registre o "porquê" das decisões importantes e mantenha tudo sincronizado com o código. Documentação não é a parte chata depois do trabalho real: é o que faz seu trabalho real existir para os outros.