Substituir um README de 2400 linhas por doze guias.
Um staff engineer numa plataforma B2B de observabilidade gravou o setup do ambiente de desenvolvimento uma vez. O tempo até ao primeiro PR de novos colaboradores caiu de três semanas para uma.
01
O documento de onboarding de engenharia era um README com 2400 linhas. Era exaustivo e indigno de confiança. Algumas secções referiam um sistema de build que tinha sido substituído. Outras assumiam uma versão de SO que portátil nenhum da empresa ainda corria. A frase "isto deve simplesmente funcionar" aparecia dezassete vezes.
Cada novo engenheiro batia nas mesmas falhas: extensão do Postgres em falta, versão errada do Node, o certificado SSL que precisava de ser regenerado, as quatro variáveis de ambiente que ninguém tinha documentado. Cada falha virava uma DM a um engenheiro sénior. Ao segundo mês de uma vaga de contratação, os seniores estavam a passar metade da semana com onboarding.
A solução que toda a gente propunha era "reescrever o README." Três engenheiros tinham tentado no ano anterior. Cada reescrita estava ótima durante duas semanas, depois desatualizava. O README apodrecia porque não tinha dono. O custo estava distribuído por todos os engenheiros seniores que respondiam às mesmas DM.
02
O setup foi gravado de raiz num portátil acabado de receber, com o Capture a correr. Cada passo e cada falha foram narrados. O resultado foi um guia de vinte e três passos com capturas do setup tal como ele está hoje.
O guia substituiu o README. Os novos colaboradores abriam-no no primeiro dia e iam fazendo. Os seis pontos de falha conhecidos ganharam guias curtos de troubleshooting próprios, ligados a partir do principal.
Quando um passo muda (atualização de uma ferramenta, variável de ambiente nova), o passo afetado volta a ser gravado. Dois minutos de trabalho, não uma reescrita do README. As DM aos seniores ligadas ao onboarding caíram de seis por novo colaborador na primeira semana para cerca de uma. Essa que sobra costuma ser uma pergunta interessante.
03
- 01Fazer o setup ao vivo.
Portátil novo, Capture a correr. Narrar cada passo, falhas incluídas.
- 02Tratar as falhas como cidadãs de primeira.
Cada modo de falha conhecido ganha o seu próprio guia curto de troubleshooting.
- 03Tudo ligado a partir de um sítio.
O wiki de engenharia tem uma única entrada: começar por aqui.
- 04Manter passo a passo.
Voltar a gravar o passo afetado quando uma ferramenta muda. Não o guia inteiro.
- 05Medir o tempo até primeiro PR.
O sucesso do onboarding mede-se pelo tempo até ao primeiro PR enviado.
04
O tempo até primeiro PR caiu de três semanas para uma. Os engenheiros seniores recuperaram a primeira semana. O volume de DM ligadas a onboarding desceu cerca de 80%.
O padrão alastrou. O runbook de on-call recebeu o mesmo tratamento. O processo de revisão de PR foi gravado. O fluxo de deploy foi gravado. O wiki de engenharia tem hoje doze guias, não 2400 linhas de README praticamente desatualizado.
Grave um workflow.
Extensão Chrome gratuita. Sem registo.
Customer Success reformou o Zoom de onboarding.
Chamadas de 45 minutos passaram a guias de 12 minutos. O território cresceu 80% sem contratar.
Operações reconstruiu a biblioteca de SOP antes da auditoria.
Vinte e um processos, gravados pelos próprios donos. SOC 2 fechou duas semanas mais cedo.
TI cortou um terço dos tickets de Tier 1.
Vinte perguntas repetidas, vinte guias, oito semanas. As segundas recuperaram as tardes.