Pular para o conteúdo
Criação de Apps

README: como escrever o arquivo de apresentação do seu projeto

Resposta rápida

O README é um arquivo, geralmente em Markdown, que fica na raiz do projeto e explica o que ele faz, como instalar, como usar e como contribuir. Ele é a primeira coisa que visitantes e futuros colaboradores leem no GitHub. Um README claro economiza dúvidas e mostra cuidado com o trabalho.

Neste artigo
  1. O que é o README
  2. O que incluir
  3. Estrutura simples
  4. Erros comuns

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.

  1. Nome e descrição curta: uma ou duas frases dizendo o que o projeto faz e para quem.
  2. Demonstração: captura de tela, GIF ou link do projeto no ar, se houver.
  3. Requisitos: versões de linguagem, banco de dados ou ferramentas necessárias.
  4. Instalação: os comandos em ordem, para copiar e colar.
  5. Como usar: um exemplo mínimo que funcione.
  6. 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.
  7. Como contribuir: regras simples para sugerir mudanças, se você aceita colaboração.
  8. 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.

  • README
  • GitHub
  • Documentação
  • Markdown

Perguntas frequentes

O README precisa ser em inglês?

Não. Escreva no idioma de quem vai usar o projeto. Se o público for internacional, vale oferecer uma versão em inglês também.

Qual o tamanho ideal de um README?

O suficiente para alguém entender o projeto e rodá-lo. Projetos pequenos funcionam com uma página; os maiores podem apontar para uma documentação separada.

Preciso incluir imagens?

Não é obrigatório, mas uma captura de tela ou um GIF curto ajuda a mostrar o resultado rapidamente, principalmente em apps com interface.

Leia também

Produtividade

Markdown para anotações: guia rápido de sintaxe para iniciantes

Poucos símbolos bastam para organizar suas notas em qualquer app.

· 2 min de leitura
Criação de Apps

Git e GitHub para iniciantes: o que são e como usar

O que cada um faz, os comandos essenciais e o fluxo mais simples para guardar o histórico dos seus códigos.

· 5 min de leitura
Criação de Apps

Variáveis de ambiente e arquivo .env: senhas fora do código

O jeito certo de guardar chaves de API, senhas de banco e outros segredos do seu projeto.

· 5 min de leitura
Criação de Apps

GitHub Pages: como publicar um site estático grátis

Com uma conta no GitHub e uma página HTML, você coloca um site simples no ar em poucos passos.

· 2 min de leitura

Deixe seu comentário