Por que o onboarding de engenharia via README sempre apodrece
Todo README de onboarding de engenharia apodrece em dois trimestres. O defeito é estrutural, não editorial, e reescrever com mais força não conserta nada.
- Tempo até a primeira PR mergeada
- 1 semana
- DMs no Slack na semana 1
- 1
- "Isso deveria funcionar"
- 17 vezes
- Setup concluído sem ajuda
- 90%
A versão curta.
Um README é um documento único que tenta ser o registro canônico de cada passo que uma nova contratação de engenharia precisa para começar a trabalhar. O padrão falha de um jeito específico: apodrece em dois trimestres, e o apodrecimento não é problema de redação. É um problema de estrutura, porque um único arquivo precisa rastrear um sistema que muda todos os dias entre versões do Postgres, versões do Node, certificados SSL, túneis de VPN, variáveis de ambiente e os quatro scripts em `bin/` que ninguém possui. Reescrever o README com mais cuidado garante duas semanas limpas, e depois o mesmo apodrecimento volta. A saída é parar de tratar onboarding como documento.
Os 17 pontos onde o README mente
Um README não mente por má-fé. Ele mente porque cada afirmação tem meia-vida mais curta do que a cadência de revisão do arquivo. A frase "isso deveria funcionar" apareceu dezessete vezes no README de 2.400 linhas que Pedro, staff engineer numa plataforma de observabilidade B2B, substituiu no trimestre passado. Cada ocorrência marcava um ponto onde o autor tinha esgotado a paciência num caso de borda.
O catálogo abaixo vem do diff de um README de onboarding real, série B, time de sessenta e cinco engenheiros.
| Tipo de mentira | Frase típica | Realidade | |
|---|---|---|---|
| 1 | Drift de versão | "Instale o Node 18" | Node 20.6+ obrigatório, 18 quebra num decorator TypeScript |
| 2 | Ferramenta substituída | "Rodar make build" | Makefile removido no T2, trocado por um script Bun |
| 3 | Silêncio na config | "Adicione as variáveis de ambiente" | Quatro vars não documentadas travam o servidor de dev |
| 4 | Screenshot velho | Print antigo do console AWS | Console foi redesenhado, o botão está em outro menu |
| 5 | Suposição de OS | "Brew install Postgres" | No Linux precisa apt, sem caminho alternativo |
| 6 | Suposição de rede | "A VPN deveria conectar" | O firewall corporativo bloqueia a troca de cert no macOS Sonoma |
| 7 | Ordem errada | Passos 4 e 5 invertidos | A ordem listada corrompe a base local |
| 8 | Buraco de permissão | "Você deve ter acesso" | Novas contratações recebem acesso no terceiro dia, não no primeiro |
| 9 | Branch trocado | "Checkout em main" | A branch padrão virou trunk há seis meses |
| 10 | Caminho de secrets | "Pegue do vault" | O caminho mudou, a CLI exige uma flag |
| 11 | Meio passo | "Rodar as migrations" | O script de migration precisa de uma flag que o README pula |
| 12 | Dependência fantasma | Sem menção ao Redis | Sem Redis rodando, o serviço de auth crasha em silêncio |
| 13 | "Deveria" não verificado | "Isso deveria funcionar" | Não funciona, a falha é silenciosa e os logs ficam vazios |
| 14 | Mudança de fornecedor | "Chaves de teste do Stripe" | Sandbox do Stripe substituída por um mock interno |
| 15 | Script de bin/ | "Rodar bin/setup" | O script não é tocado desde 2023 e assume Python 2 |
| 16 | Referência morta | "Veja o guia de deploy" | O guia foi deletado numa limpeza do Confluence |
| 17 | Sessão de navegador | "Login em localhost" | O cert autoassinado é bloqueado pelo Chrome sem override manual |
make build"main"trunk há seis mesesbin/setup"Cada mentira é pequena. A soma transforma a primeira semana de um novo contratado em garimpo. A história de documentação do time de engenharia na mesma plataforma chegou a medir isso: cada nova contratação esbarrava em cerca de seis dessas falhas na semana 1.
Por que reescrever o README nunca segura
Três engenheiros tinham tentado reescrever o README no ano anterior ao trabalho de Pedro. Cada reescrita ficou excelente por duas semanas. Depois apodrecia. O padrão não tem nada a ver com disciplina ou talento de redação. É estrutural, dá para prever a falha sem conhecer o time.
Um README tem um único autor por vez. A primeira reescrita acontece quando o custo do apodrecimento fica visível (uma semana inteira de DMs aos seniores por nova contratação). Alguém se voluntaria, bloqueia dois dias, entrega um arquivo sólido. Faz o merge. Na semana seguinte, uma ferramenta sobe de versão, um script muda, uma variável de ambiente é adicionada. O autor original já partiu para outra. A mudança não é propagada porque o custo de editar o arquivo é maior do que o custo de responder em DM no Slack para quem perguntar. O apodrecimento recomeça na semana 3.
Compare com o jeito como o código se mantém atualizado. O código não apodrece no mesmo ritmo porque o build quebra quando o código fica defasado. O README é um artefato somente leitura do ponto de vista do build. Nada quebra quando ele fica desatualizado. A pesquisa do NNGroup sobre por que usuários da web escaneiam em vez de ler descreve o padrão dominante: o leitor escaneia, não lê inteiro, e confia menos no documento a cada afirmação errada que encontra. Quando a nova contratação esbarra na terceira mentira, ela fecha o arquivo e abre um DM. O senior responde, porque responder é mais rápido do que reescrever a linha 1.847.
A conclusão estrutural é nítida. Um README é o formato errado porque o custo de manutenção é pago por uma pessoa e o custo da falha é pago por outra, e essa assimetria torna o apodrecimento inevitável. Reescrever não muda a assimetria. Compra duas semanas e zera o cronômetro.
O caminho que funciona alinha o mantenedor com quem mexe na ferramenta: quem altera um script regrava só a etapa afetada em dois minutos, sem sprint de doc. É isso que o fluxo de gravação da extensão Chrome propõe.
O que entra no lugar de um README
O que entra no lugar de um README são doze guias curtos, um por modo de falha, gravados pelo engenheiro que resolveu aquela falha pela última vez. O README de 2.400 linhas da plataforma de observabilidade foi substituído por doze guias. Os números falam direto: o tempo até a primeira PR mergeada caiu de três semanas para uma. Os DMs no Slack na semana 1 aos seniores caíram de seis para um por nova contratação. O setup concluído sem ajuda passou de "quase nunca" para noventa por cento. São métricas que um staff engineer ou engineering manager num SaaS B2B de 50 a 200 engenheiros consegue usar para defender a virada com a liderança.
A estrutura é específica. Um guia principal, vinte e três passos, percorre o happy path num laptop novo. Cada modo de falha conhecido (versão errada do Node, certificado SSL, vars de ambiente faltando, túnel de VPN, extensão do Postgres, os quatro scripts em bin/) tem o próprio guia curto de troubleshooting. O guia principal aponta para o guia de troubleshooting no exato passo onde aquela falha costuma aparecer. A pessoa não escaneia 2.400 linhas atrás do erro. Ela clica.
A forma de cada guia importa. Os passos são numerados. Cada um traz uma captura da tela atual real, não uma aproximação de um ano atrás. Cada um carrega o comando exato, não uma versão parafraseada. A narração explica por que o passo existe, não só o que ele faz, porque uma nova contratação para de confiar em docs que se leem como um dump de comandos. A pesquisa do NNGroup sobre o padrão de leitura em F na web explica por que esse formato segura: o leitor lê as primeiras palavras de cada linha, olha a captura, segue em frente. A granularidade por passo casa com o scan.
Quando uma ferramenta muda, só o passo afetado é regravado. Dois minutos, não uma reescrita do README. O custo de manutenção fica baixo o bastante para o engenheiro que fez a mudança levar a refatoração até o fim. O custo da falha para de compor porque a próxima contratação nunca esbarra no passo defasado. O caminho completo vive em o argumento dos guias passo a passo.
O custo de manter o README
O custo de manter o README não é pago pelo autor. É pago pelos seniores que respondem aos DMs e pelas novas contratações cuja primeira PR escorrega quinze dias. É isso que torna o custo invisível para o engenheiro que poderia reescrever o arquivo. A contabilidade está errada, e contabilidade ruim protege padrões ruins.
Faça a conta com sessenta e cinco engenheiros, quatro novas contratações por trimestre, três semanas de ramp-up. Cada nova contratação gera cerca de seis DMs na semana 1. Cada DM custa vinte minutos uma vez contado o context-switching. São duas horas de senior por nova contratação só nas falhas óbvias, antes da ajuda real de setup. Quatro contratações por trimestre a duas horas cada totalizam oito horas por trimestre em perguntas que um guia teria absorvido.
O custo por contratação é mais nítido. Duas semanas de ramp parado significam zero PR mergeada na primeira quinzena. A 200.000 USD de custo carregado por senior por ano (o número conservador para uma plataforma de observabilidade série B), duas semanas a zero output saem por cerca de 7.700 USD por nova contratação, algo perto de R$ 38.500 ao câmbio atual, que a empresa engole porque o README apodreceu. Multiplique por quatro contratações por trimestre e a fatura anual chega perto de 123.000 USD.
O custo compõe porque não aparece em nenhum OKR trimestral. O imposto de apodrecimento é pago pela organização de engenharia como um todo e não sai na review de ninguém. A saída é colocar o custo na mesma pessoa que pode evitá-lo: quem mexe na ferramenta conserta o passo nos mesmos cinco minutos. É isso que o plano para times a partir de 12 USD por assento cobre, e o cálculo costuma justificar a despesa já no primeiro trimestre.
Existe um custo mais difuso. Uma nova contratação que coleciona muitas mentiras na semana 1 começa o cargo com a calibração errada. Aprende que doc é pouco confiável, que o jeito de obter resposta é mandar DM aos seniores, que processos apodrecem. Essa calibração é difícil de reverter quando a liderança mais tarde pede para esses mesmos engenheiros escreverem boa documentação.
Quando um README ainda é o formato certo
Um README ainda é o formato certo para coisas que mudam pouco e são lidas por inteiro. Três casos qualificam, o resto pertence aos guias gravados.
O primeiro caso é a declaração de propósito do projeto. O que o sistema faz, o que não faz, quem é dono. Essa informação muda no máximo uma vez por ano. O leitor escaneia, entende, segue. Uma frase de README é a forma certa.
O segundo caso é o guia de contribuição de um projeto open source. Estilo de código, convenção de branch, formato de PR no GitHub, contributor license agreement. Essas regras valem para contribuintes pontuais que nunca vão estar no Slack do time. A pessoa que lê não tem acesso a um workspace privado, não tem um senior para abrir DM e precisa de um texto autônomo legível direto no GitHub. O README é o veículo certo aqui.
O terceiro caso é a visão de arquitetura de alto nível, o diagrama global e a descrição de quem fala com quem. Esse documento muda quando a arquitetura muda, uma ou duas vezes por ano num sistema estável. Ele é lido para entender, não para executar, e o padrão de leitura única casa com o formato README.
Tudo que muda mais de uma vez por trimestre e é lido para executar não cabe ali. Setup do ambiente de dev, fluxo de deploy, runbook de plantão, padrões de debug no Datadog ou Grafana, as quatro dependências fantasmas que travam o serviço de auth. Tudo isso apodrece na velocidade das ferramentas subjacentes e ganha com gravação por passo que se atualiza em dois minutos.
Uma segunda referência sobre essa divisão vive em como documentar o fluxo de onboarding de clientes, que defende o mesmo argumento em outro domínio. O defeito estrutural é o mesmo: um arquivo único não acompanha um processo que muda mais rápido do que ele é revisado. A saída atravessa os dois domínios.
Perguntas frequentes.
- Quanto tempo leva para substituir um README de 2.400 linhas por guias gravados?
Pedro, staff engineer da plataforma de observabilidade B2B, gravou o guia principal de vinte e três passos em cerca de quatro horas, narração incluída. Cada um dos seis guias de troubleshooting levou em torno de trinta minutos. O total ficou abaixo de dois dias-pessoa, mais rápido do que qualquer uma das três reescritas de README que o time tinha tentado antes. Os números detalhados estão na história de documentação do time de engenharia.
- Quem mantém os guias quando o autor original sai do projeto?
Quem muda a ferramenta regrava o passo afetado. O custo de manutenção é de dois minutos por mudança, baixo o bastante para os engenheiros levarem isso a sério em vez de empurrar para outro. O padrão segura porque o custo da atualização é pago pela mesma pessoa que disparou a necessidade da atualização, o que elimina a assimetria que faz um README apodrecer. Uma revisão trimestral pega passos que alguém esqueceu de regravar, mas o custo por passo é tão baixo que o trimestral é só uma rede de segurança.
- E os engenheiros que preferem ler texto em vez de assistir um guia?
Os guias do Capture não são vídeos. Cada passo é uma captura de tela mais uma descrição escrita, exportável em Markdown, HTML ou PDF. Quem quer só passar o olho faz isso do mesmo jeito que faria num README, com a diferença de que as capturas estão atualizadas. A narração é opcional e renderiza como texto alinhado a cada passo. O formato otimiza para o scan-reader, que a pesquisa do NNGroup sobre legibilidade, leitura e compreensão mostra ser como a doc técnica é de fato consumida.
- Isso funciona para projetos open source com contribuintes externos?
Em parte. A visão de arquitetura, o guia de contribuição e a declaração de propósito ficam no README porque contribuintes externos não têm acesso a um workspace privado. O setup do ambiente de dev pode ser exportado em PDF ou HTML e commitado no repositório, o que dá a esses contribuintes o mesmo formato escaneável sem forçar os mantenedores a carregar um arquivo de 2.400 linhas. A divisão fica clara: estático no README, executável nos guias gravados.
- A partir de qual tamanho de time a virada começa a compensar?
A virada começa a pagar por volta de quinze engenheiros, quando o imposto de DM aos seniores fica visível o bastante para justificar a mudança. Abaixo disso, o README costuma ser mantido pela mesma pessoa que o lê. Acima de cinquenta engenheiros, o custo de interromper os seniores fica alto demais para o formato existente. O staff engineer ou engineering manager num SaaS B2B na faixa de 50 a 200 é o persona com o retorno mais nítido.
Pronto para trocar seu README de engenharia por doze guias gravados?
O Capture grava o setup uma vez num laptop novo, narra cada passo e exporta um guia por etapa que se atualiza em dois minutos quando uma ferramenta muda. O tempo até a primeira PR mergeada caiu de três semanas para uma no caso estudado.
O argumento dos guias passo a passo: seis times, um padrão
A pessoa sênior que conhece o workflow de cor vira gargalo. O wiki apodrece. O Loom que ninguém assiste empilha poeira no Drive. Os guias passo a passo quebram esse padrão nos seis times que vimos rodar isso em produção.
Como documentar um fluxo de onboarding de clientes em 2026
A maioria das documentações de onboarding morre em oito semanas porque ninguém regrava quando a UI muda. A saída não é um redator melhor. É um método recording-first que toma dez minutos por refresh.
A regra dos 12 passos: por que o tamanho prediz o fracasso
Quase todo time de documentação escreve guias mais longos do que deveria. O tamanho joga contra você, e 12 passos é o teto operacional acima do qual a taxa de conclusão desaba.
Grave um workflow.
Extensão Chrome gratuita. Sem cadastro.