Como reduzir o onboarding de engenharia de meses para dias

A experiência típica de integração de engenharia em uma empresa em crescimento é mais ou menos assim. Semana um: configure seu ambiente de desenvolvimento usando um guia parcialmente desatualizado. Passe duas horas descobrindo que uma etapa foi pulada porque a dependência mudou. Pergunte no Slack. Espere alguém responder. Semana dois: acompanhe alguém da equipe que explica a arquitetura verbalmente enquanto você tenta fazer anotações. Entenda talvez 40% dela. Semana três: receba a tarefa de corrigir um pequeno bug. Passe a maior parte da semana entendendo a base de código bem o suficiente para encontrar o arquivo relevante. Semana quatro: finalmente envie seu primeiro PR. Ele é revisado e você descobre que violou três convenções que ninguém lhe contou.

Entre seis e oito semanas, você está começando a ser moderadamente produtivo. Aos três meses, você consegue trabalhar de forma independente na maioria das tarefas. A equipe trata esse cronograma como normal porque é o mesmo para cada nova contratação, o que faz parecer que é inerente à função e não um sintoma de falta de documentação.

É um sintoma de falta de documentação.

O que reduz o tempo de integração pela metade

Pesquisas e experiências práticas apontam consistentemente para a mesma conclusão: a maior alavanca individual na velocidade de integração de engenharia é a qualidade e a integridade da documentação disponível para as novas contratações. Equipes com documentações abrangentes e atualizadas realizam a integração em três a quatro semanas. Equipes sem elas levam de oito a doze.

A diferença está em quais atividades o tempo do novo contratado é gasto. Em uma equipe bem documentada, o novo contratado passa a primeira semana lendo: a arquitetura do sistema, as principais decisões e seus fundamentos, as convenções da equipe, o guia de introdução. Eles têm dúvidas, mas as perguntas são específicas e direcionadas, em vez de amplas e contextuais. Em uma equipe sem documentação, o novo contratado passa as primeiras semanas reconstruindo esse entendimento por meio de conversas, o que é mais lento, menos completo e também consome o tempo de outros engenheiros.

Os cinco documentos de integração que mais importam

Nem toda documentação ajuda na integração da mesma forma. Estas cinco têm o maior impacto.

Visão geral da arquitetura do sistema. Um mapa dos principais serviços, como eles se comunicam e pelo que cada um é responsável. Isso dá ao novo contratado um modelo mental de todo o sistema antes de mergulhar em qualquer componente. Sem isso, eles passam semanas construindo esse modelo por meio de inferências e perguntas, e o modelo que constroem frequentemente é incompleto ou incorreto.

Guia de introdução. Instruções passo a passo para configurar o ambiente de desenvolvimento, compilar o projeto, executar testes e implantar uma alteração. Cada minuto que este guia economiza é um minuto que o novo contratado não passa pedindo ajuda a outra pessoa. Teste este guia fazendo com que um não engenheiro o siga. Se ele não conseguir colocar o projeto em execução, o guia tem lacunas.

Registros de decisão. O raciocínio documentado por trás das principais escolhas técnicas. Por que o serviço de autenticação é separado do monólito. Por que esse banco de dados específico foi escolhido. Por que o pipeline de dados usa processamento em lote. Sem isso, o novo contratado comete erros que repetem problemas já resolvidos ou passa tempo debatendo decisões que a equipe tomou meses atrás.

Convenções da equipe. Padrões de codificação, expectativas de revisão de PR, formato de mensagens de commit, procedimentos de implantação, protocolos de resposta a incidentes. As regras não escritas que os membros experientes da equipe seguem inconscientemente e os novos contratados aprendem por tentativa e erro quando não estão escritas. As três convenções que ninguém contou ao novo contratado e que foram apontadas em sua primeira revisão de PR? Elas deveriam estar neste documento.

Quem é dono do quê. Um mapa das responsabilidades da equipe, propriedade do sistema e a quem perguntar sobre áreas específicas. Isso por si só economiza horas do problema de "quem sabe sobre X?" que assola equipes em crescimento.

Por que os documentos de integração ficam desatualizados (e como corrigir isso)

A ironia da documentação de integração é que ela normalmente é criada de forma reativa, nas semanas anteriores ou posteriores à chegada de uma nova contratação, pelos engenheiros seniores que já estão mais sobrecarregados. A documentação é criada sob pressão, muitas vezes incompleta, e como foi criada para uma contratação específica, raramente é mantida depois que essa pessoa não precisa mais dela. Quando a próxima contratação chega, os documentos estão parcialmente desatualizados e o ciclo se repete.

Documentação autogestora muda isso ao gerar materiais de integração continuamente a partir da atividade em andamento da equipe. A documentação da arquitetura permanece atualizada porque é gerada a partir de PRs e discussões de design. Os registros de decisão são capturados à medida que as decisões são tomadas em reuniões e threads do Slack. A documentação de convenções reflete a prática real, em vez de diretrizes aspiracionais de seis meses atrás.

Quando a próxima contratação chega, os materiais de integração já existem e já estão atualizados. Sem corrida de trabalho de documentação, sem tirar engenheiros seniores de seus projetos, sem páginas de wiki feitas às pressas que estarão desatualizadas no próximo trimestre.

Medindo a melhoria

Se você está defendendo o investimento em documentação de integração, estas são as métricas que importam.

Tempo para o primeiro PR significativo. A medida mais direta da velocidade de rampa. Monitore isso para cada nova contratação antes e depois de melhorar a documentação.

Perguntas feitas no primeiro mês. Conte as DMs do Slack e as perguntas que teriam sido respondidas pelos documentos. Uma queda significativa indica que os documentos estão funcionando.

Tempo de interrupção do engenheiro sênior. Monitore quanto tempo os engenheiros seniores passam respondendo a perguntas de novos contratados antes e depois de os documentos existirem. Isso mede o benefício para a equipe existente, não apenas para o novo contratado.

Confiança auto-relatada. Pergunte semanalmente aos novos contratados quão confiantes eles se sentem navegando na base de código de forma independente. A inclinação desta curva melhora visivelmente com uma boa documentação.

Com um salário de engenharia sênior de $180.000 a $220.000, reduzir o tempo de rampa de dez semanas para quatro economiza cerca de $22.000 a $27.000 por contratação. Com dez contratações por ano, isso representa mais de $200.000 em produtividade recuperada, financiada inteiramente por documentação que pode ser gerada automaticamente.

Perguntas frequentes

E se o nosso sistema for complexo demais para ser documentado? Se for complexo demais para documentar, é complexo demais para as novas contratações aprenderem de forma eficiente, o que significa que a própria complexidade é um gargalo de crescimento. A documentação força a clareza sobre o que o sistema é e como funciona, o que é valioso mesmo que a documentação não seja perfeita. Comece com a visão geral da arquitetura e itere.

Deveríamos designar um parceiro de integração (buddy) em vez disso? Ambos. Um parceiro fornece a integração social e cultural que os documentos não conseguem. Os documentos fornecem a integração técnica e arquitetônica que um parceiro não consegue entregar de forma abrangente em conversas. O tempo do parceiro é melhor gasto em tomada de decisões, apresentações e contexto cultural do que explicando o pipeline de implantação.

Como mantemos os documentos atualizados? A resposta estrutural é documentação que se mantém sozinha a partir da atividade de engenharia em tempo real. A resposta manual é atribuir um proprietário a cada documento e revisá-lo trimestralmente. A resposta estrutural é mais confiável porque não depende de ninguém se lembrar de fazer a revisão.

Leitura recomendada: O custo real da integração de engenharia, Como escalar uma equipe de engenharia, Débito de documentação. Páginas relacionadas: Documentos que se escrevem sozinhos, Solução de integração, Para equipes de engenharia.