Quanto a documentação ruim realmente está custando para você?

Uma documentação ruim é um daqueles custos que se escondem à vista de todos. Ninguém tem uma linha de orçamento para "tempo desperdiçado porque as coisas não estão registradas por escrito." Ninguém rastreia "decisões rediscutidas porque ninguém documentou a discussão original." Ninguém mede "bugs causados por engenheiros que não entenderam por que o sistema foi construído dessa maneira." Mas todos esses são custos reais e, quando você os soma, mesmo para uma equipe de engenharia modesta, o total é grande o suficiente para valer a pena ser abordado.

Veja como calcular o seu número.

Categoria 1: Interrupções de engenheiros seniores

Cada pergunta que um colega responde verbalmente é um tempo que poderia ter sido gasto em trabalho de engenharia. O custo é a interrupção em si mais o tempo de recuperação: cerca de 25 minutos de foco perdido por interrupção.

Seus dados de entrada:

• Número de engenheiros seniores

• Estimativa de interrupções por dia para perguntas que poderiam ser respondidas por documentação (geralmente de 3 a 8)

• Custo médio de recuperação por interrupção: 25 minutos

• Taxa horária total de custo do engenheiro sênior

Exemplo: 5 engenheiros seniores × 5 interrupções/dia × 25 minutos × $95/hora × 250 dias úteis = $248.000/ano

A maioria das equipes subestima a contagem de interrupções porque cada interrupção individual parece trivial. Monitore isso por uma semana e o número geralmente será maior do que o esperado.

Categoria 2: Atrasos na integração (onboarding)

Cada semana que um novo contratado passa se adaptando que poderia ter sido encurtada por uma documentação melhor é uma semana de salário paga para um rendimento reduzido.

Seus dados de entrada:

• Número de contratações de engenharia por ano

• Semanas estimadas de tempo de adaptação com a documentação atual

• Semanas estimadas de tempo de adaptação com uma boa documentação (geralmente 40-60% menor)

• Custo mensal total de um novo contratado

Exemplo: 8 contratações/ano × 4 semanas de tempo de adaptação evitável × $4.500/semana de custo total = $144.000/ano

Categoria 3: Decisões rediscutidas

Quando decisões passadas não são documentadas, as equipes perdem tempo de reunião debatendo questões que já foram resolvidas. O custo é o tempo de reunião multiplicado pelo número de participantes.

Seus dados de entrada:

• Estimativa de horas por mês gastas em reuniões rediscutindo decisões passadas

• Número médio de participantes nessas reuniões

• Custo médio da taxa horária total

Exemplo: 4 horas/mês × 5 participantes × $85/hora × 12 meses = $20.400/ano

Isso parece pouco, mas o custo indireto é maior: decisões rediscutidas atrasam o trabalho que depende delas, e o atraso se propaga em cascata pela sprint.

Categoria 4: Perda de conhecimento por desligamentos

Quando um engenheiro-chave sai e seu conhecimento não está documentado, a equipe sofre um impacto na produtividade enquanto reconstrói o contexto que partiu com ele.

Seus dados de entrada:

• Número de saídas de profissionais-chave por ano

• Semanas estimadas de produtividade reduzida da equipe por desligamento

• Custo da equipe por semana durante a produtividade reduzida

Exemplo: 2 saídas/ano × 6 semanas de velocidade reduzida × $15.000/semana de custo de equipe × 30% de redução de produtividade = $54.000/ano

Categoria 5: Erros por falta de contexto

Bugs e erros causados por engenheiros que não entenderam por que um sistema foi construído da maneira que foi. Estes são os mais difíceis de quantificar, mas frequentemente os mais caros, porque um mal-entendido conceitual pode produzir bugs que são difíceis de diagnosticar e caros de corrigir.

Seus dados de entrada:

• Estimativa de incidentes por ano atribuíveis à falta de documentação ou contexto

• Custo médio por incidente (tempo de engenharia para diagnosticar, corrigir e revisar)

Exemplo: 6 incidentes/ano × $5.000 de custo médio = $30.000/ano

Categoria 6: Ferramentas de IA operando sem contexto

Suas ferramentas de codificação por IA, agentes internos e automação funcionam com uma fração de seu potencial porque o contexto de engenharia de que precisam não está documentado e pesquisável. Esta é a categoria mais difícil de quantificar porque é um custo de oportunidade, e não um custo direto: o valor que suas ferramentas de IA poderiam fornecer se tivessem o contexto adequado versus o valor que fornecem sem ele.

Impacto estimado: Se suas ferramentas de IA forem de 30% a 50% mais eficazes com uma documentação abrangente, e sua equipe passar de 2 a 3 horas por dia interagindo com ferramentas de IA, a produtividade recuperada de um contexto melhor documentado é significativa, mesmo em estimativas conservadoras.

Somando tudo

Para uma equipe de engenharia de 20 pessoas com contratação moderada e qualidade típica de documentação:

Isso antes de contar o custo de oportunidade da IA. Para uma equipe de 20 pessoas, o custo documentado total de uma documentação ruim é de cerca de meio milhão de dólares por ano, o que equivale ao custo de duas a três contratações de engenharia gastas em problemas que uma documentação abrangente eliminaria em grande parte.

A comparação

Documentação autodocumentável que gera e se mantém sozinha a partir da atividade no GitHub da sua equipe, conversas no Slack e reuniões custa uma fração de um salário de engenharia. Se ela resolver pelo menos 50% dos custos acima, o retorno sobre o investimento será de dez a vinte vezes o custo da ferramenta.

A questão para a maioria dos líderes de engenharia não é se a documentação ruim é cara. É que ninguém somou os custos antes, porque cada categoria é distribuída em dezenas de pequenas ineficiências que individualmente parecem insignificantes.

Elas não são insignificantes. Elas são apenas invisíveis até que alguém as calcule.

Perguntas frequentes

Esses números são realistas para equipes menores? Dimensione-os proporcionalmente. Uma equipe de dez pessoas com menos contratações e menos interrupções terá um total menor, mas o custo por engenheiro é semelhante. A maioria das equipes de dez ou mais pessoas está perdendo mais de $100 mil por ano com problemas de documentação. O custo cresce de forma não linear com o tamanho da equipe porque o gargalo do conhecimento tácito piora à medida que a equipe cresce.

E se nós já tivermos alguma documentação? Ajuste as estimativas para as áreas onde seus documentos são fortes. Se seus documentos de integração são bons, mas sua documentação de decisões está ausente, o custo de integração será menor, mas o custo de rediscussão será maior. A maioria das equipes possui bolsões de boa documentação cercados por lacunas significativas.

Como convencemos a liderança a investir em documentação? Calcule seu número específico usando as categorias acima com os dados reais da sua equipe. Apresente-o juntamente com o custo da solução. O cálculo do ROI geralmente é convincente o suficiente por si só, porque o custo do problema é grande e o custo da solução é comparativamente pequeno.

Leituras recomendadas: O custo de escrever documentos de engenharia, O custo real da integração de engenheiros, O fator ônibus, Bons documentos são um multiplicador de 10x. Páginas relacionadas: Documentos autodocumentáveis, Para equipes de engenharia, Retenção de conhecimento.