Documentos de engenharia custam US$ 50.000/ano. Ninguém fala sobre isso.

Existe um item de linha no seu orçamento de engenharia que ninguém contabiliza: o tempo que seus engenheiros passam escrevendo e mantendo a documentação. Ele não aparece em nenhum plano de projeto, nunca é estimado no planejamento de sprints e raramente é discutido em retrospectivas. Mas ele é real, é caro e, para a maioria das equipes, é um dos maiores custos não monitorados do departamento.

Um engenheiro sênior nos EUA que ganha entre $180.000 e $220.000 por ano custa aproximadamente de $85 a $105 por hora quando se incluem benefícios e despesas operacionais. Um engenheiro sênior no Reino Unido que ganha entre £80.000 e £120.000 custa aproximadamente de £50 a £75 por hora com base nos mesmos critérios.

Se esse engenheiro passar cinco horas por semana com documentação, escrevendo páginas de wiki, atualizando documentos de arquitetura, documentando alterações de API, explicando decisões em textos longos em vez de código, o custo anual fica entre $22.000 e $27.000 nos EUA. Em uma equipe de dez engenheiros onde cada um passa de três a cinco horas por semana em documentos, o total é de $130.000 a $270.000 por ano em tempo de engenharia gasto escrevendo em vez de construindo.

Esses números são conservadores. Eles não incluem o tempo gasto no Slack explicando coisas que deveriam estar na documentação, o tempo gasto em reuniões reconstruindo contextos que nunca foram documentados, ou o tempo gasto respondendo às mesmas perguntas de integração toda vez que um novo engenheiro entra.

Para onde o tempo realmente vai

As cinco horas por semana não são um bloco único de escrita focada de documentação. Elas são dispersas ao longo da semana em pequenos fragmentos, cada um carregando seu próprio custo de troca de contexto.

Documentação pós-PR. Depois de entregar uma alteração significativa, o engenheiro atualiza a wiki, a documentação da API, o diagrama de arquitetura e quaisquer READMEs relevantes. Isso pode levar de trinta minutos a uma hora por PR significativo, mas a troca de contexto do código para a prosa é exaustiva de uma forma que o tempo sozinho não consegue capturar.

Responder a perguntas que deveriam estar nos documentos. Um engenheiro júnior pergunta por que o serviço de pagamentos está estruturado dessa forma. Um gerente de produto pergunta como funciona o pipeline de dados. Uma nova contratação pergunta onde encontrar o guia de implantação. Cada pergunta leva de dez a vinte minutos, e as respostas são dadas verbalmente ou em conversas de Slack, onde se perderão em poucos dias.

Manter os documentos existentes. Uma refatoração torna três páginas de wiki incorretas. Uma alteração na API invalida o guia de integração. Uma atualização de dependência quebra as instruções de configuração. Alguém tem que encontrar e corrigir isso, e o trabalho é tão tedioso que muitas vezes não acontece até que alguém siga as instruções desatualizadas e perca uma tarde inteira.

Documentação de integração (onboarding). Cada nova contratação gera uma onda de atividade de documentação à medida que a equipe percebe que as coisas que estavam guardando em suas mentes precisam ser escritas para alguém que não tem o contexto. Essa é a documentação reativa em sua forma mais cara: criada sob pressão de tempo, muitas vezes incompleta e raramente mantida depois que a nova contratação não precisa mais dela.

O custo de oportunidade

O custo da documentação não se resume apenas às horas de salário. Trata-se do que essas horas poderiam ter sido usadas em seu lugar.

Cinco horas por semana do tempo de um engenheiro sênior equivalem a cinco horas de pensamento arquitetônico, revisão de código, mentoria, depuração ou trabalho em funcionalidades. Ao longo de um ano, para um único engenheiro, isso representa cerca de 250 horas, ou cerca de seis semanas inteiras de trabalho, redirecionadas do trabalho para o qual foram contratados.

Os engenheiros que sentem o custo de oportunidade de forma mais aguda são tipicamente os mais seniores, porque são eles que têm mais contexto para documentar e as alternativas de uso de tempo mais valiosas. O fardo da documentação recai mais pesadamente sobre as pessoas que a organização menos pode se dar ao luxo de distrair.

A alternativa

O cálculo de custos acima assume que a documentação exige tempo humano de engenharia, o que tem sido verdade desde que a engenharia de software existe. A documentação autoescrita muda essa premissa.

Quando a documentação é gerada e mantida automaticamente a partir da atividade de engenharia que já está acontecendo — as fontes que atualmente guardam seu conhecimento de forma transitória (PRs e commits do GitHub, conversas de Slack, gravações de reuniões, documentos de design) —, o custo da escrita humana cai para quase zero.

Os engenheiros ainda revisam os documentos gerados, corrigem imprecisões e adicionam o contexto que o sistema automatizado perdeu. Mas o trabalho de base de converter a atividade institucional em documentação estruturada e pesquisável é tratado pelo sistema, e não pelas pessoas cujo tempo custa de $85 a $105 por hora.

Para uma equipe de dez engenheiros que passam cinco horas por semana em documentos, eliminar até 80% desse esforço manual economiza entre $100.000 e $215.000 por ano em tempo de engenharia recuperado. Isso equivale a contratar um engenheiro adicional, financiado inteiramente por não desperdiçar o tempo dos engenheiros que você já possui.

Perguntas frequentes

Cinco horas por semana é realista? Pesquisas com equipes de engenharia consistentemente apontam o tempo de documentação entre quatro e oito horas por semana para engenheiros seniores, com esse número aumentando durante os períodos de integração e após grandes refatorações. Cinco horas é uma estimativa moderada, e muitas equipes descobririam que o número real é maior se passassem a rastreá-lo.

E as equipes que simplesmente não escrevem documentos? Elas pagam o custo de outra forma: através de tempos de integração mais longos, mais interrupções para os engenheiros seniores, mais erros decorrentes de uma arquitetura mal compreendida e maior perda de conhecimento quando as pessoas saem. O custo de não escrever documentos costuma ser maior do que o custo de escrevê-los, apenas é menos visível porque é distribuído em dezenas de pequenas ineficiências em vez de aparecer como um único item de linha.

Como calcular o custo para a sua própria equipe? Conte o número de engenheiros, estime a média de horas semanais que eles gastam em atividades relacionadas à documentação (escrever, manter, responder a perguntas que deveriam estar nos documentos) e multiplique pelo custo por hora com impostos e benefícios incluídos. A maioria das equipes acha o número surpreendentemente alto quando realmente faz o cálculo.

Leitura recomendada: Por que os documentos de engenharia importam, Por que os engenheiros odeiam escrever documentos, Quanto a documentação ruim está custando para você?. Páginas relacionadas: Documentação autoescrita, Para equipes de engenharia.