README no GitHub: o arquivo que mostra o seu portfólio

README apresenta o problema, o resultado, as decisões e o caminho reproduzível para executar um projeto. No portfólio, ele permite avaliar clareza antes de abrir código. Um README forte não é uma coleção de badges: é documentação que uma pessoa consegue seguir numa pasta limpa.

O teste criou uma livraria mínima, publicou num bare e clonou novamente:

git clone /tmp/grupo-git-readme.56CT94/central.git copia-limpa

A primeira tela precisa responder três perguntas

Nomeia o projeto, mostra o que ele entrega e informa para quem serve. “Projeto de estudo” não diferencia nada. “Catálogo de livros para praticar Git” define domínio e objetivo em uma linha. Depois, uma imagem real do resultado pode ajudar se existe interface.

No clone, os arquivos necessários estavam presentes:

find . -maxdepth 1 -type f -print | sort

O .env real não viajou. O modelo e a instrução permitiram reconstruí-lo.

Sete blocos cobrem a leitura de portfólio

Uma ordem útil é: promessa, demonstração, recursos, tecnologias, instalação, decisões e próximos passos. Licença e contribuição entram quando o projeto aceita uso ou colaboração externa. Não transforme nomes em subtítulos vazios; cada seção deve reduzir uma dúvida.

O README de teste usa apenas o necessário:

rg '^## ' README.md

Ele tem 47 palavras, um tamanho adequado ao programa minúsculo:

wc -w README.md

Projetos maiores precisam de mais contexto, não de um alvo artificial de palavras. Arquitetura, dados de exemplo, variáveis e deploy só entram quando existem.

Markdown organiza sem esconder conteúdo

Use um H1 para nome, H2 para seções, listas para opções e blocos de código para comandos. Texto alternativo descreve imagens. Tabelas servem a comparações, não layout. HTML suportado pelo GitHub pode existir, mas Markdown simples é mais portável e fácil de revisar no diff.

O trecho executado foi lido diretamente do clone:

sed -n '1,18p' README.md | sed '/^```/d' | tr -d '\140'

No arquivo real, os dois comandos estão cercados como Bash. O pipeline de inspeção removeu as cercas e os acentos graves para exibir o conteúdo como resultado de terminal, sem fingir que o GitHub foi aberto no teste.

Print e badge precisam carregar informação

Uma captura deve mostrar estado relevante e ter texto alternativo. GIF ajuda a demonstrar interação curta, mas pode pesar e não substitui instrução escrita. Badge comunica build, cobertura ou versão quando aponta para dado confiável. Uma parede de tecnologias sem contexto disputa atenção com o projeto.

Evite imagens externas frágeis e segredos em screenshots. Se o projeto usa dados pessoais, monte uma conta e um conjunto fictícios para demonstração.

Como rodar é um teste, não uma promessa

O clone seguiu a instrução sem completar passos de memória:

cp .env.example .env
sh app.sh

Versão do runtime, instalação, migração, seed e variáveis precisam aparecer quando necessários. “Rode o projeto normalmente” transfere conhecimento oculto para o leitor e falha numa máquina nova.

Depois da execução, .env continuou ignorado:

git status --short
git ls-files .env

Os dois comandos ficaram sem stdout: o clone permaneceu limpo e .env não era rastreado.

Decisões demonstram raciocínio

Explique por que escolheu uma solução e qual limite aceitou. No exemplo, “não acessa rede nem banco” evita que a pessoa espere infraestrutura inexistente. Em um projeto real, documente autenticação, persistência, responsividade, acessibilidade e trade-offs que aparecem no código.

Uma lista de tecnologias sem relação não prova domínio. Diga onde cada uma entra: PostgreSQL persiste pedidos; React compõe a interface; testes de contrato protegem a API. Isso permite ao recrutador conectar ferramenta e decisão.

Antes e depois muda a capacidade de executar

Um README genérico diz “instale as dependências e rode”. A versão revisada declara versão do runtime, comando exato, arquivo de ambiente, migração, dados de exemplo e saída esperada. A diferença não é tom de marketing: é reduzir decisões ocultas que só a pessoa autora conhecia.

Faça o teste com alguém que não acompanhou o desenvolvimento, ou simule essa pessoa num clone limpo. Não responda durante a primeira tentativa. Anote o ponto de parada, a mensagem exibida e a informação ausente. Depois corrija a documentação, apague a cópia e repita. O critério de sucesso é chegar ao mesmo resultado com as instruções, não elogiar a aparência do arquivo.

Valide também links relativos e nomes de branch. Uma imagem que funciona na sua pasta pode quebrar no GitHub por diferença de maiúsculas. Um comando que assume master falha quando o projeto usa main. README faz parte do código: entra em revisão, acompanha mudança de interface e recebe correção quando a execução muda.

Perfil e projetos fixados exigem curadoria

O README de perfil vive num repositório público com o mesmo nome da conta, um recurso do GitHub. A criação e os projetos fixados dependem da sua conta e não foram alterados aqui. Use a tela para apresentar foco profissional, contatos que você deseja publicar e poucos trabalhos consistentes.

O commit do README testado ficou rastreável:

git --no-pager log -1 --oneline

Sua missão é clonar seu projeto numa pasta temporária e seguir somente o texto. Anote toda decisão que você completou de cabeça, corrija o README e repita. Ao final, conecte remote e clone, tags e releases e o fluxo de time numa história de portfólio que outra pessoa realmente consegue executar.