Porque o acolhimento de engenharia via README apodrece sempre
Todo o README de acolhimento apodrece em dois trimestres. O defeito é estrutural, não editorial, e reescrevê-lo com mais força não corrige nada.
- Tempo até primeira PR aceite
- 1 semana
- DM no Slack na semana 1
- 1
- "Isto devia funcionar"
- 17 vezes
- Setup terminado sem ajuda
- 90 %
A versão curta.
Um README é um único ficheiro que se propõe ser o registo canónico de cada passo que um novo engenheiro precisa para começar. O modo de falha é específico: apodrece em dois trimestres, e o apodrecimento não é um problema de redação. É um problema estrutural, porque um único ficheiro tenta seguir um sistema que muda todos os dias entre versões de Postgres, versões de Node, certificados SSL, túneis VPN, variáveis de ambiente e os quatro scripts em `bin/` que ninguém possui. Reescrever o README com mais força compra duas semanas limpas, depois o mesmo apodrecimento volta. A saída passa por deixar de tratar o acolhimento como um documento.
Os 17 sítios onde o README mente
Um README não mente por má vontade. Mente porque cada afirmação tem uma meia-vida mais curta do que a cadência de revisão do ficheiro. A frase "isto devia funcionar" aparecia dezassete vezes no README de 2 400 linhas que o Vasco, staff engineer numa plataforma de observabilidade B2B com sede em Lisboa, substituiu no trimestre passado. Cada ocorrência marcava um sítio onde o autor original tinha esgotado a paciência para explicar o caso limite.
O catálogo a seguir vem do diff de um README de acolhimento real, série B, equipa de sessenta e cinco engenheiros.
| Tipo de mentira | Frase típica | O que era verdade | |
|---|---|---|---|
| 1 | Versão desfasada | "Instalar Node 18" | Node 20.6 mínimo, a 18 falha num decorator TypeScript |
| 2 | Ferramenta substituída | "Correr make build" | Makefile removido no T2, substituído por um script Bun |
| 3 | Silêncio na configuração | "Adicionar as variáveis de ambiente" | Quatro variáveis por documentar bloqueiam o servidor de dev |
| 4 | Captura de ecrã obsoleta | Screenshot antigo da consola AWS | Consola redesenhada, o botão está noutro menu |
| 5 | Pressuposto de SO | "Brew install Postgres" | Em Linux é preciso apt, não há caminho alternativo no documento |
| 6 | Pressuposto de rede | "A VPN deve ligar" | A firewall corporativa bloqueia a troca de certificado em macOS Sonoma |
| 7 | Ordem trocada | Passos 4 e 5 invertidos | A ordem listada corrompe a base de dados local |
| 8 | Lacuna de permissões | "Já deves ter acesso" | Os novos colegas só recebem acesso ao terceiro dia, não ao primeiro |
| 9 | Branch por omissão | "Fazer checkout de main" | A branch foi renomeada para trunk há seis meses |
| 10 | Caminho dos segredos | "Vai buscar ao vault" | O caminho mudou, a CLI exige uma flag adicional |
| 11 | Passo a meio | "Correr as migrações" | O script de migração precisa de uma flag que o README ignora |
| 12 | Dependência fantasma | Sem menção a Redis | Sem Redis a correr, o serviço de auth cai em silêncio |
| 13 | "Devia" por verificar | "Isto devia 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 bin/ | "Correr bin/setup" | O script não é tocado desde 2023 e assume Python 2 |
| 16 | Referência partida | "Ver o guia de deploy" | O guia foi apagado numa limpeza de Confluence |
| 17 | Sessão de browser | "Login em localhost" | O certificado 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 colega num exercício de arqueologia. A história de documentação da equipa de engenharia na mesma plataforma mediu o efeito: cada novo colega caía em cerca de seis destas falhas na primeira semana.
Porque a reescrita do README nunca aguenta
Três engenheiros já tinham tentado reescrever o README no ano anterior ao trabalho do Vasco. Cada reescrita ficou excelente durante duas semanas. Depois apodreceu. O padrão é estrutural, e dá para prever a falha sem conhecer a equipa.
Um README tem um único autor a cada momento. A primeira reescrita acontece quando o custo do apodrecimento se torna visível (uma semana de DM aos seniores por cada novo colega). Alguém oferece-se voluntariamente, bloqueia dois dias e produz um ficheiro sólido. Faz merge. Na semana seguinte uma ferramenta sobe de versão, um script muda, uma variável de ambiente é adicionada. O autor original já está noutra coisa. A alteração não é repercutida porque o custo de editar o ficheiro é mais alto do que o custo de responder em DM ao colega que pergunta. O apodrecimento recomeça na terceira semana.
Compare-se com a forma como o código se mantém atual. O código não apodrece ao mesmo ritmo porque o build estraga-se quando o código fica desfasado. O README é um artefacto só de leitura do ponto de vista do build. Nada falha quando ele perde a passada. A investigação do Nielsen Norman Group sobre porque os utilizadores fazem scan em vez de ler descreve o padrão: as pessoas varrem, não leem na íntegra, e dão cada vez menos crédito a um documento a cada afirmação errada que encontram. À terceira mentira, o novo colega fecha o ficheiro e abre uma DM. O sénior responde, porque é mais rápido do que reescrever a linha 1 847.
A conclusão é nítida. Um README é o formato errado porque o custo de manutenção é suportado por uma pessoa e o custo de falha por outra, e essa assimetria torna o apodrecimento inevitável. Reescrever não muda a assimetria. Compra duas semanas e repõe o contador a zero.
O caminho que funciona alinha o mantenedor com quem altera a ferramenta: quem modifica um script grava de novo o passo afetado em dois minutos, sem sprint de documentação. É isso que está construído à volta da extensão de Chrome do Capture.
O que substitui um README
O que substitui um README são doze guias curtos, um por modo de falha, gravados pelo engenheiro que resolveu essa falha mais recentemente. O README de 2 400 linhas da plataforma de observabilidade foi substituído por doze guias. Os números falam por si: o tempo até à primeira PR aceite caiu de três semanas para uma. As DM no Slack na semana 1 caíram de seis para uma por novo colega. O setup terminado sem ajuda passou de "quase nunca" a noventa por cento.
A estrutura é precisa. Um guia principal de vinte e três passos percorre o caminho feliz num portátil acabado de configurar. Cada modo de falha conhecido (a versão errada de Node, o certificado SSL, as variáveis em falta, o túnel VPN, a extensão de Postgres, os quatro scripts em bin/) tem o seu guia curto de troubleshooting. O guia principal aponta para esse guia no passo exato em que a falha costuma surgir. O leitor deixa de varrer 2 400 linhas. Clica.
A forma de cada guia importa. Os passos são numerados. Cada um traz uma captura do ecrã real, não uma aproximação de há um ano. Cada um traz o comando exato, não uma paráfrase. A narração explica porque é que o passo existe, porque os novos colegas deixam de confiar em documentos que se leem como um despejo de comandos. A investigação do Nielsen Norman Group sobre o padrão de leitura em F na web explica porque é que o formato aguenta: lê-se as primeiras palavras de cada linha, olha-se para a captura, avança-se.
Quando uma ferramenta muda, só o passo afetado é gravado de novo. Dois minutos de trabalho. O custo de manutenção fica baixo o suficiente para que o engenheiro que fez a mudança o suporte de facto. O custo de falha deixa de compor porque o próximo colega nunca cai no passo desfasado. O percurso completo está em o caso a favor 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 a DM e pelos novos colegas cuja primeira PR escorrega quinze dias. É isso que torna o custo invisível para o engenheiro que poderia reescrever o documento. A contabilidade está errada, e contabilidade errada protege padrões errados.
Faça-se a conta com sessenta e cinco engenheiros, quatro novos colegas por trimestre. Cada novo colega gera cerca de seis DM na semana 1 dirigidas a seniores. Cada DM custa vinte minutos depois de contado o context-switching. São duas horas de tempo sénior por novo colega só nas falhas óbvias. Quatro novos colegas por trimestre a duas horas por cabeça dão oito horas trimestrais em perguntas que um guia teria absorvido.
O custo por novo colega é mais nítido. Duas semanas de ramp travado significam zero PR feitas na primeira quinzena. A 200 000 USD de custo carregado por sénior por ano, duas semanas a zero output custam cerca de 7 700 USD por novo colega (à volta de 7 100 € ao câmbio recente), que a empresa engole porque o README apodreceu. Multiplique-se por quatro novos colegas por trimestre e a fatura anual aproxima-se de 123 000 USD, perto de 113 000 €.
O custo compõe porque não está em nenhum OKR trimestral. O imposto do apodrecimento é pago pela organização de engenharia em agregado e não aparece na review de ninguém. A saída passa por colocar o custo na mesma pessoa que o pode evitar: quem muda a ferramenta corrige o passo, nos mesmos cinco minutos. É isso que o plano de equipa a partir de 12 USD por lugar cobre, e a conta justifica a decisão quase sempre no primeiro trimestre.
Há um custo mais difuso. Um novo colega que apanha demasiadas mentiras na semana 1 começa o cargo com a calibração errada. Aprende que a documentação não é fiável, que se obtém respostas em DM aos seniores, que os processos apodrecem. Essa calibração é difícil de inverter quando a liderança, mais tarde, pede a esses mesmos engenheiros para escreverem documentação decente.
Quando um README continua a ser o formato certo
Um README continua a ser o formato certo para o que muda raramente e se lê na íntegra. Três casos qualificam, e 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 é o dono. Esta informação muda no máximo uma vez por ano. Uma frase de README é a forma certa para isto.
O segundo caso é o guia de contribuição de um projeto open source. Estilo de código, convenção de nomes de branches, formato de PR no GitHub, contributor license agreement. Estas regras aplicam-se a contribuidores ocasionais que nunca vão estar no Slack da equipa. O leitor não tem acesso a um workspace privado de Capture, não tem um sénior a quem mandar DM, e beneficia de um texto autocontido que se lê diretamente no GitHub.
O terceiro caso é a vista de arquitetura de alto nível, o diagrama global e a descrição de quem fala com quem. Muda uma a duas vezes por ano num sistema estável. Lê-se para compreender, não para executar, e o padrão de leitura única encaixa no formato.
Tudo o que muda mais do que uma vez por trimestre e se lê para executar não cabe. Setup de ambiente, fluxo de deploy, runbook de oncall, padrões de debug em Datadog ou Grafana, as quatro dependências fantasma que bloqueiam o serviço de auth. Tudo isto apodrece à velocidade das ferramentas subjacentes e ganha com uma gravação por passo que se atualiza em dois minutos.
Uma segunda leitura sobre esta divisão vive em como documentar o acolhimento de clientes, que defende o mesmo argumento noutro domínio. Um único ficheiro não consegue seguir um processo que muda mais depressa do que é revisto.
Perguntas frequentes.
- Quanto tempo demora a substituir um README de 2 400 linhas por guias gravados?
O Vasco, staff engineer na 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 à volta de trinta minutos. O total cabe em menos de dois dias-pessoa, mais rápido do que qualquer uma das três tentativas anteriores de reescrita do README. Detalhes na história de documentação da equipa de engenharia.
- Quem mantém os guias quando o autor original passa a outra coisa?
Quem altera a ferramenta volta a gravar o passo afetado. O custo de manutenção é de dois minutos por mudança, baixo o suficiente para que os engenheiros o suportem em vez de o empurrarem para outro. O padrão aguenta porque o custo da atualização é pago pela mesma pessoa que desencadeou a necessidade, o que remove a assimetria que faz apodrecer um README. Uma revisão trimestral apanha os passos que alguém se esqueceu de gravar, mas o custo por passo é tão baixo que a revisão trimestral funciona apenas como rede de segurança.
- E os engenheiros que preferem ler texto a ver um guia?
Os guias do Capture não são vídeos. Cada passo é uma captura de ecrã com uma descrição escrita, exportável em Markdown, HTML ou PDF. Quem quer apenas varrer o documento fá-lo tal como faria com um README, com a diferença de que as capturas estão atualizadas. A narração é opcional e renderiza-se em texto alinhado a cada passo. O formato otimiza para o leitor que faz scan, que a investigação do Nielsen Norman Group sobre legibilidade, leitura e compreensão mostra ser a forma como a documentação técnica é realmente consumida.
- Funciona para projetos open source com contribuidores externos?
Em parte. A vista de arquitetura, o guia de contribuição e a declaração de propósito ficam no README porque os contribuidores externos não têm acesso a um workspace privado. O setup de ambiente de dev pode ser exportado em PDF ou HTML e versionado no repo, o que dá aos contribuidores externos o mesmo formato pesquisável sem obrigar os mantenedores a manter um ficheiro de 2 400 linhas. A divisão fica simples: conteúdo estático no README, fluxos executáveis em guias gravados.
- A partir de que tamanho de equipa é que a mudança compensa?
A mudança começa a pagar-se por volta dos quinze engenheiros, quando o imposto das DM aos seniores se torna visível o suficiente para justificar a alteração. Abaixo disso, o README costuma ser mantido pela mesma pessoa que o lê. Acima dos cinquenta engenheiros, o custo de interromper seniores ultrapassa o que o formato consegue absorver. O staff engineer ou o engineering manager de uma SaaS B2B na faixa dos 50 a 200 é a persona que retira o maior retorno desta troca.
Pronto para trocar o README de engenharia por doze guias gravados?
O Capture grava o setup uma vez num portátil novo, narra cada passo e exporta um guia por passo que se atualiza em dois minutos quando uma ferramenta muda. O tempo até à primeira PR aceite cai de três semanas para uma no caso estudado.
Guias passo a passo: seis equipas, uma só mecânica
A pessoa sénior que conhece o fluxo de trabalho de cor torna-se o estrangulamento. O wiki apodrece. O Loom que ninguém vê acumula pó num ficheiro. Os guias passo a passo quebram esse padrão nas seis equipas que vimos a fazer isto em produção.
Como documentar o acolhimento de clientes em 2026
A maioria da documentação de acolhimento morre em oito semanas porque ninguém a volta a gravar quando a interface muda. A solução não passa por escrever melhor. Passa por um método recording-first que demora dez minutos por atualização.
A regra dos 12 passos: porque o tamanho prediz o fracasso da documentação
Quase todas as equipas escrevem guias mais longos do que deviam. O tamanho joga contra a equipa, e 12 passos é o tecto operacional acima do qual a taxa de conclusão se desfaz.
Grave um workflow.
Extensão Chrome gratuita. Sem registo.