artubss Elaborando READMEs Efetivos
Visão Geral
READMEs respondem perguntas que seu público terá. Diferentes públicos precisam de informações diferentes - um contribuidor de um projeto OSS precisa de contexto diferente do seu eu futuro abrindo uma pasta de configuração.
Sempre pergunte: Quem vai ler isso, e o que precisa saber?
Processo
Passo 1: Identifique a Tarefa
Pergunte: "Qual tarefa de README você está trabalhando?"
| Tarefa | Quando |
|---|---|
| Criar | Novo projeto, sem README ainda |
| Adicionar | Precisa documentar algo novo |
| Atualizar | Capacidades mudaram, conteúdo está desatualizado |
| Revisar | Verificar se o README ainda está preciso |
Passo 2: Perguntas Específicas da Tarefa
Criando README inicial:
- Que tipo de projeto? (veja Tipos de Projeto abaixo)
- Que problema resolve em uma frase?
- Qual é o caminho mais rápido para "funciona"?
- Algo notável para destacar?
Adicionando uma seção:
- O que precisa ser documentado?
- Onde deveria ficar na estrutura existente?
- Quem mais precisa dessa informação?
Atualizando conteúdo existente:
- O que mudou?
- Leia o README atual, identifique seções desatualizadas
- Proponha edições específicas
Revisando/atualizando:
- Leia o README atual
- Verifique contra o estado real do projeto (package.json, arquivos principais, etc.)
- Sinalize seções desatualizadas
- Atualize a data de "Última revisão" se presente
Passo 3: Sempre Pergunte
Após rascunhar, pergunte: "Há algo mais para destacar ou incluir que eu possa ter deixado passar?"
Tipos de Projeto
| Tipo | Público | Seções-Chave | Template |
|---|---|---|---|
| Open Source | Contribuidores, usuários do mundo todo | Instalação, Uso, Contribuindo, Licença | templates/oss.md |
| Pessoal | Seu eu futuro, visualizadores de portfólio | O que faz, Stack de tecnologias, Aprendizados | templates/personal.md |
| Interno | Colegas de time, novos contratados | Setup, Arquitetura, Runbooks | templates/internal.md |
| Config | Seu eu futuro (confuso) | O que está aqui, Por quê, Como estender, Armadilhas | templates/xdg-config.md |
Pergunte ao usuário se não estiver claro. Não presuma padrões OSS para tudo.
Seções Essenciais (Todos os Tipos)
Todo README precisa no mínimo de:
- Nome - Título auto-explicativo
- Descrição - O que + por quê em 1-2 frases
- Uso - Como usá-lo (exemplos ajudam)
Referências
section-checklist.md- Quais seções incluir por tipo de projetostyle-guide.md- Erros comuns em README e orientação de prosausing-references.md- Guia para materiais de referência mais profundos