Trocando um README de 2.400 linhas por doze guias.
Um staff engineer numa plataforma B2B de observabilidade gravou o setup do ambiente de dev uma vez. O tempo até o primeiro PR de novatos caiu de três semanas pra uma.
01
O doc de onboarding de engenheiros era um README de 2.400 linhas. Era detalhado e nada confiável. Algumas seções referenciavam um build system que tinha sido substituído. Outras assumiam uma versão de OS que nenhum laptop da empresa rodava mais. A frase "isso deveria simplesmente funcionar" aparecia dezessete vezes.
Todo engenheiro novo batia nas mesmas falhas: extensão do Postgres faltando, versão errada do Node, o cert SSL que precisava ser regerado, as quatro variáveis de ambiente que ninguém tinha documentado. Cada falha virava um DM no Slack pra um sênior. No segundo mês de uma onda de contratação, os seniores gastavam metade da semana com onboarding.
A solução que todo mundo propunha era "reescrever o README." Três engenheiros tentaram no ano anterior. Cada reescrita era ótima por duas semanas e depois apodrecia. O README apodrecia porque ninguém era dono. O custo ficava distribuído por todo sênior que respondia os mesmos DMs.
02
O setup foi gravado do zero num laptop limpo, com o Capture rodando. Cada passo e cada falha foi narrada. O entregável foi um guia de vinte e três passos com screenshots do setup atual de verdade.
O guia substituiu o README. Os novatos abriam no primeiro dia e seguiam direto. Os seis modos de falha conhecidos ganharam guias curtos de troubleshooting próprios, linkados a partir do guia principal.
Quando uma etapa muda (uma versão nova de ferramenta, uma variável de ambiente diferente), a etapa afetada é regravada. Dois minutos de trabalho, não uma reescrita do README. Os DMs de onboarding mandados pra seniores caíram de seis por novato na semana 1 pra cerca de um. Esse um costuma ser uma pergunta interessante de verdade.
03
- 01Faça o setup ao vivo.
Laptop limpo, Capture rodando. Narre cada passo, inclusive as falhas.
- 02Trate as falhas como parte do guia.
Cada modo de falha conhecido ganha seu próprio guia curto de troubleshooting.
- 03Linkado de um lugar só.
O wiki de engenharia tem uma entrada: comece aqui.
- 04Mantenha passo a passo.
Regrave a etapa afetada quando uma ferramenta muda. Não o guia inteiro.
- 05Acompanhe o tempo até o primeiro PR.
O sucesso do onboarding é medido pelo tempo até o primeiro PR no ar.
04
O tempo até o primeiro PR caiu de três semanas pra uma. Os seniores recuperaram a primeira semana. O volume de DMs ligados a onboarding caiu uns 80%.
O padrão se espalhou. O runbook de plantão recebeu o mesmo tratamento. O processo de revisão de PR foi gravado. O fluxo de deploy foi gravado. O wiki de engenharia hoje são doze guias, não 2.400 linhas de um README majoritariamente desatualizado.
Grave um workflow.
Extensão Chrome gratuita. Sem cadastro.
Customer Success aposentou a call de onboarding.
Calls de 45 minutos viraram guias de 12 minutos. A carteira cresceu 80% sem contratar.
Operações reconstruiu a biblioteca de SOPs antes da auditoria.
Vinte e um processos, gravados pelos próprios donos. SOC 2 fechou duas semanas adiantado.
TI cortou um terço dos tickets de Tier 1.
Vinte perguntas repetidas, vinte guias, oito semanas. As segundas recuperaram a tarde.