O que é um bom README: estrutura, conteúdo e o que ninguém lê
1. Por que o README é o cartão de visitas do seu projeto
Um README bem escrito é a diferença entre um repositório que morre na gaveta e um que ganha comunidade, contribuições e estrelas. Ele é o primeiro — e muitas vezes o único — contato que um visitante terá com seu trabalho. Um README ruim custa caro: contribuidores em potencial desistem antes de entender o propósito, issues duplicadas inundam o repositório porque ninguém leu as instruções básicas, e o projeto perde credibilidade.
A diferença entre um README funcional e um inspirador está nos detalhes. O funcional responde "o que isso faz" e "como instalar". O inspirador responde "por que isso importa" e "como posso contribuir para algo maior". Ambos são necessários, mas o segundo é o que transforma visitantes em colaboradores.
2. A estrutura essencial que todo README deve ter
Cabeçalho: título, descrição e badges
O cabeçalho deve comunicar maturidade em segundos. Comece com o nome do projeto, uma descrição de uma linha e badges de build, cobertura de testes, versão e licença.
# NomeDoProjeto
[](https://travis-ci.org/usuario/projeto)
[](https://codecov.io/gh/usuario/projeto)
[](https://github.com/usuario/projeto/releases)
[](LICENSE)
Ferramenta CLI para converter Markdown em PDF com suporte a templates customizados.
Índice automatizado
Projetos com mais de 500 linhas de README precisam de um índice. Use links âncora para facilitar a navegação:
## Índice
- [Instalação](#instalação)
- [Uso](#uso)
- [Configuração](#configuração)
- [Contribuição](#contribuição)
- [Licença](#licença)
Pré-requisitos e instalação
A seção de instalação deve levar o usuário do zero ao "Hello World" em no máximo três passos:
## Pré-requisitos
- Python 3.8 ou superior
- pip 21.0+
## Instalação
1. Clone o repositório:
```bash
git clone https://github.com/usuario/nome-do-projeto.git
```
2. Instale as dependências:
```bash
cd nome-do-projeto
pip install -r requirements.txt
```
3. Execute o comando de teste:
```bash
python -m nome_do_projeto --versao
```
3. Conteúdo que realmente importa (e o que quase ninguém coloca)
Exemplos de uso reais com saída esperada
Este é o bloco mais ignorado e o mais valioso. Mostre não apenas o comando, mas o resultado que o usuário deve esperar:
## Exemplos de uso
Converter um arquivo Markdown para PDF:
```bash
md2pdf entrada.md -o saida.pdf
Saída esperada no terminal:
Arquivo 'entrada.md' convertido com sucesso.
PDF gerado em: saida.pdf
Tamanho: 1.2 MB
Páginas: 15
Seção de configuração e variáveis de ambiente
Documente cada variável com nome, descrição e valor padrão:
## Configuração
| Variável | Descrição | Padrão |
|-----------------------|-------------------------------|--------------|
| `MD2PDF_TEMPLATE` | Caminho para template customizado | `default` |
| `MD2PDF_MARGEM` | Margem em mm | `20` |
| `MD2PDF_DEBUG` | Ativa logs detalhados | `false` |
Estrutura de diretórios explicada
Forneça o mapa mental do projeto:
## Estrutura do projeto
nome-do-projeto/
├── src/
│ ├── conversor.py # Lógica principal de conversão
│ └── templates/ # Templates HTML para PDF
├── tests/
│ └── test_conversor.py # Testes unitários
├── docs/ # Documentação adicional
├── README.md
└── LICENSE
4. O que ninguém lê (e por que você deve escrever mesmo assim)
Algumas seções são ignoradas por 90% dos visitantes, mas são essenciais para os 10% que realmente importam: mantenedores e contribuidores sérios.
Licença, código de conduta e contribuição
Esse "entulho legal" é o que protege seu projeto. Ninguém lê até que um problema legal surja. Inclua:
## Licença
Distribuído sob a licença MIT. Veja [LICENSE](LICENSE) para mais informações.
## Código de Conduta
Este projeto segue o [Código de Conduta do Contributor Covenant](https://www.contributor-covenant.org/). Ao participar, você concorda em respeitá-lo.
## Contribuição
1. Faça um fork do projeto
2. Crie uma branch (`git checkout -b feature/nova-feature`)
3. Commit suas mudanças (`git commit -m 'Adiciona nova feature'`)
4. Push para a branch (`git push origin feature/nova-feature`)
5. Abra um Pull Request
Changelog e versão
Ninguém lê changelog até que uma atualização quebre a compatibilidade. Mantenha um arquivo CHANGELOG.md separado com o formato Keep a Changelog:
## Changelog
### [2.1.0] - 2025-03-15
#### Adicionado
- Suporte a templates customizados
- Nova flag `--margem` para controle de margens
### [2.0.0] - 2025-02-01
#### Modificado
- **Breaking**: API de conversão agora retorna objeto em vez de string
- Melhorias de performance (40% mais rápido)
Agradecimentos e créditos
A seção que vira "scroll infinito" mas humaniza o projeto:
## Agradecimentos
- [@joaosilva](https://github.com/joaosilva) pela implementação do suporte a tabelas
- [@mariaoliveira](https://github.com/mariaoliveira) pelos testes de integração
- Inspirado pelo projeto [awesome-readme](https://github.com/matiassingers/awesome-readme)
5. README para diferentes públicos
Biblioteca vs. aplicação vs. ferramenta CLI
Cada tipo de projeto exige um foco diferente:
- Biblioteca: API completa, exemplos de código, guia de migração
- Aplicação: capturas de tela, fluxo de uso, configuração de ambiente
- Ferramenta CLI: lista completa de comandos, flags, exemplos de pipe
Equilíbrio entre iniciantes e experts
Use seções colapsáveis para esconder detalhes avançados:
<details>
<summary>Configuração avançada (para usuários experientes)</summary>
### Personalização de templates
Crie um arquivo `template.html` na raiz do projeto e aponte a variável `MD2PDF_TEMPLATE`.
</details>
FAQ e Troubleshooting
O que ninguém escreve, mas todos procuram:
## Perguntas frequentes
**O PDF gerado está cortando conteúdo?**
Aumente a margem com a flag `--margem 30`.
**O comando `md2pdf` não é encontrado?**
Verifique se o Python está no PATH ou use `python -m md2pdf`.
6. Boas práticas visuais e de manutenção
Uso moderado de emojis, tabelas e imagens
Emojis podem humanizar, mas excesso polui. Use tabelas para dados comparativos e imagens (com texto alternativo) para fluxos complexos:
## Fluxo de conversão
*Diagrama mostrando as etapas de conversão: Markdown → HTML → PDF*
Atualização contínua: checklist
Crie um checklist no final do README para não deixá-lo virar legacy:
## Checklist de manutenção
- [ ] Exemplos de uso funcionam com a versão atual?
- [ ] Badges de build estão verdes?
- [ ] Variáveis de ambiente documentadas?
- [ ] Changelog atualizado?
Ferramentas que geram README automaticamente
Ferramentas como readme.so, Make a README e Readme Generator ajudam, mas nunca substituem a curadoria humana. Use-as como ponto de partida, não como produto final.
7. Armadilhas comuns e como evitá-las
README inflado com roadmap que nunca é atualizado
Roadmaps são traiçoeiros. Se for incluir, use datas realistas e remova itens obsoletos:
## Roadmap (próximos 3 meses)
- [ ] Suporte a exportação em EPUB (abril/2025)
- [x] Suporte a templates customizados (março/2025) ✅
Exemplos de código quebrados ou desatualizados
Teste todos os exemplos antes de cada release. Um exemplo quebrado destrói a credibilidade instantaneamente.
README-driven development
Escreva o README antes de codificar. Isso força você a pensar na experiência do usuário antes de implementar. O README vira o contrato de design do projeto.
Referências
- Make a README — Guia interativo para criar READMEs eficientes, com templates e boas práticas.
- Awesome README — Curadoria dos melhores READMEs do GitHub, com exemplos de estrutura e design.
- Keep a Changelog — Padrão recomendado para manter changelogs legíveis e úteis para usuários e contribuidores.
- Contributor Covenant — Código de conduta amplamente adotado em projetos open source, com templates prontos.
- readme.so — Ferramenta visual para gerar READMEs com seções pré-definidas e personalizáveis.
- Documentação oficial do GitHub sobre READMEs — Guia oficial sobre como criar e formatar READMEs em repositórios GitHub.
- Standard Readme — Especificação formal para estrutura de READMEs, usada por projetos como Node.js e Angular.