Um novo engenheiro custa US$ 15 mil/mês enquanto se adapta. A documentação corta isso pela metade.

Um novo engenheiro custa seu salário integral desde o primeiro dia, enquanto produz um rendimento próximo de zero durante seu período de adaptação (ramp period). Com um salário de engenheiro sênior nos EUA de $180.000 a $220.000, o custo mensal total com encargos é de aproximadamente $15.000 a $18.000. Durante as semanas em que esse engenheiro está lendo código, fazendo perguntas, participando de apresentações e, de modo geral, absorvendo o contexto em vez de entregar código, a empresa está pagando o preço integral por uma fração da produtividade.

Isso é totalmente normal e esperado. A questão não é se existe um período de adaptação, mas quanto tempo ele dura, e a maior alavanca individual na duração desse período é a qualidade da documentação à qual a nova contratação tem acesso.

A diferença da documentação

Em uma equipe com documentação abrangente e atualizada, a primeira semana de um novo engenheiro é assim: ler a visão geral da arquitetura, entender os principais sistemas e como eles interagem, revisar o registro de decisões para as principais escolhas técnicas, seguir o guia de configuração e implantar uma pequena alteração. Eles têm dúvidas, mas muitas delas são respondidas pela documentação, e as perguntas que restam são específicas e direcionadas, em vez de amplas e contextuais.

Em uma equipe sem documentação, a primeira semana do mesmo engenheiro parece diferente: encontrar alguém disposto a lhe explicar o sistema, absorver o que puder de uma visão geral verbal que é necessariamente incompleta, tropeçar em um processo de configuração que está parcialmente documentado e parcialmente baseado em perguntar por aí, e gastar um tempo considerável tentando entender não apenas o sistema, mas a quem perguntar sobre quais partes dele.

A diferença no tempo de adaptação é tipicamente de quatro a seis semanas para equipes bem documentadas, contra oito a doze semanas para as mal documentadas. Com um custo de $15.000 a $18.000 por mês, reduzir o período de adaptação de dez semanas para quatro economiza de $22.500 a $27.000 por contratação.

Com dez contratações de engenharia por ano, o que é típico para uma startup em crescimento, isso representa de $225.000 a $270.000 em produtividade recuperada. Para organizações maiores que contratam vinte ou mais engenheiros anualmente, a economia escala proporcionalmente.

O que contém uma boa documentação de integração (onboarding)

Nem toda documentação ajuda na integração da mesma forma. Os documentos de onboarding de maior impacto são:

Visão geral da arquitetura do sistema. Um mapa dos principais serviços, como eles se comunicam e qual é a responsabilidade de cada um. Isso dá à nova contratação um modelo mental de todo o sistema antes de mergulhar em qualquer componente individual.

Guia de introdução (getting started). Instruções passo a passo para configurar o ambiente de desenvolvimento, compilar o projeto, executar testes e implantar uma alteração. Cada minuto que o guia de configuração economiza é um minuto que a nova contratação não gasta pedindo ajuda a outra pessoa.

Decisões importantes e suas justificativas. Os registros de decisões que explicam por que o sistema foi construído da maneira como foi. Sem eles, a nova contratação cometerá erros que repetem problemas já resolvidos ou gastará tempo discutindo decisões que já foram tomadas.

Convenções da equipe. Padrões de codificação, expectativas de revisão de PR, procedimentos de implantação, protocolos de resposta a incidentes. As regras não escritas que os membros experientes da equipe seguem inconscientemente e as novas contratações aprendem por tentativa e erro quando não estão documentadas.

Quem faz o quê. Um mapa das responsabilidades da equipe, propriedade do sistema e a quem perguntar sobre áreas específicas. Isso, por si só, economiza horas de tempo da nova contratação que, de outra forma, seriam gastas descobrindo a estrutura da equipe por tentativa e erro.

Documentação que se escreve sozinha (self-writing)

A ironia da documentação de onboarding é que ela costuma ser criada de forma reativa, nas semanas anteriores ou posteriores à chegada de um novo contratado, pelos engenheiros seniores que já são os mais sobrecarregados. A documentação é criada sob pressão de tempo e, por ser feita para uma contratação específica, muitas vezes não é mantida depois que essa pessoa não precisa mais dela.

A documentação autogrável (self-writing) muda essa dinâmica ao gerar materiais de onboarding continuamente a partir da atividade em andamento da equipe. A documentação de arquitetura permanece atualizada porque é gerada a partir de PRs e discussões de design. Os registros de decisões são capturados à medida que as decisões são tomadas. A documentação de convenções reflete a prática real em vez de diretrizes aspiracionais.

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

Perguntas frequentes

Como medimos o ROI de uma melhor documentação de integração? Acompanhe o tempo até o primeiro PR significativo (ou primeira implantação em produção) para novas contratações antes e depois de melhorar a documentação. Essa é a medida mais direta do tempo de adaptação. Monitore também o número de perguntas que as novas contratações fazem em seu primeiro mês, que tende a cair significativamente quando há uma boa documentação disponível.

Qual é o documento de onboarding mais importante para criar primeiro? A visão geral da arquitetura do sistema e o guia de introdução. Juntos, eles atendem às necessidades mais imediatas do novo contratado: entender o que o sistema faz e colocá-lo para funcionar localmente.

Isso se aplica a prestadores de serviço e freelancers? Mais ainda, porque os prestadores de serviço geralmente têm contratos mais curtos e menos tolerância a longos períodos de adaptação. Uma boa documentação permite que um prestador de serviço se torne produtivo em dias em vez de semanas, o que significa que a organização obtém mais valor da contratação.

Leituras recomendadas: O fator ônibus (bus factor), O custo oculto do conhecimento tribal, Dívida de documentação. Páginas relacionadas: Documentação autogrável, Integração (Onboarding), Para equipes de engenharia.