Bons documentos são um multiplicador de engenharia de 10x

O enquadramento padrão para a documentação é que ela ajuda a pessoa que a está lendo: o novo contratado, o engenheiro júnior, o colega que trabalha em uma parte desconhecida da base de código. Isso é verdade, mas subestima drasticamente o benefício ao focar no lado errado da equação.

O benefício muito maior é para as pessoas que deixam de ser interrompidas.

O custo da interrupção

Um engenheiro sênior trabalhando em um problema complexo precisa de concentração contínua. Pesquisas sobre alternância de contexto mostram consistentemente que uma interrupção, mesmo que breve, custa muito mais do que a duração da interrupção em si. O trabalho de Gloria Mark estima o tempo de recuperação em cerca de 25 minutos para retornar ao mesmo nível de foco após uma interrupção.

Um engenheiro sênior que é interrompido dez vezes por dia por perguntas que seriam respondidas por uma boa documentação perde não apenas os dez minutos de resposta, mas cerca de quatro horas de foco produtivo devido ao custo de recuperação. Isso é metade do dia de trabalho consumido pela ausência de documentos, e o engenheiro frequentemente não percebe o que está acontecendo porque cada interrupção individual parece pequena e controlável.

As perguntas em si são inteiramente razoáveis. "Por que o serviço de autenticação está estruturado desta forma?" "Onde encontro o guia de implantação?" "Qual foi o raciocínio por trás do uso desta fila em vez de um banco de dados?" "Como o pipeline de dados lida com registros com falha?" Cada uma dessas perguntas tem uma resposta e, em uma equipe sem documentos, a resposta vive na cabeça de um engenheiro sênior e só pode ser acessada interrompendo-o.

O efeito de multiplicação

Uma boa documentação cria um efeito de multiplicação que cresce com o tamanho da equipe.

Em uma equipe de cinco pessoas, as interrupções são gerenciáveis porque a equipe é pequena e o contexto é compartilhado. Em uma equipe de vinte pessoas com cinco engenheiros seniores e quinze pessoas que precisam regularmente de contexto deles, a carga de interrupção escala de forma não linear. Cada engenheiro sênior agora é um gargalo para as perguntas de três ou quatro pessoas, e o custo agregado para a produtividade dos engenheiros seniores é substancial.

A documentação quebra esse gargalo ao disponibilizar o conhecimento dos engenheiros seniores sem exigir a atenção deles. O engenheiro júnior lê o documento de arquitetura em vez de perguntar. O novo contratado segue o guia de integração em vez de solicitar um passo a passo. O colega que trabalha em uma área desconhecida da base de código lê o registro de decisões em vez de agendar uma reunião.

Cada pergunta redirecionada de uma pessoa para um documento economiza o tempo de espera de quem pergunta e o custo de interrupção de quem responde. Com dez perguntas por dia em toda a equipe, a economia é de duas a quatro horas de tempo de engenharia sênior, o que equivale a ter um engenheiro sênior adicional cuja única contribuição é responder a perguntas por procuração.

Quem mais se beneficia

As pessoas que mais se beneficiam de uma boa documentação são normalmente os engenheiros mais seniores e mais valiosos da equipe, aqueles cujo tempo é mais caro e cuja concentração é mais crítica. Essas são as mesmas pessoas que carregam a maior carga de documentação quando os documentos são criados manualmente, o que cria uma dinâmica particularmente dispendiosa: as pessoas cujo foco é mais valioso são as mais frequentemente interrompidas, e a solução (escrever documentos) também recai sobre elas, consumindo mais do foco que deveria proteger.

A documentação auto-escrita quebra esse ciclo gerando documentos a partir da produção existente do engenheiro sênior (suas descrições de PR, suas explicações no Slack, suas contribuições em reuniões) sem exigir trabalho adicional deles. O conhecimento que eles já estão compartilhando de maneiras específicas de contexto é capturado e estruturado para que seja localizável por qualquer pessoa, a qualquer momento, sem interromper sua fonte.

Perguntas frequentes

Como medimos o custo da interrupção? Monitore o número de perguntas que os engenheiros seniores recebem via DMs do Slack e solicitações pessoais por uma semana. Multiplique por 25 minutos (o custo médio de recuperação por interrupção) para obter o tempo total de foco perdido. A maioria das equipes descobre que o número é muito maior do que imaginava.

Os engenheiros juniores simplesmente não deixarão de ler os documentos? Se os documentos estiverem atualizados, bem organizados e pesquisáveis, a adoção costuma ser alta porque a alternativa (esperar que um engenheiro sênior responda) é mais lenta. Se os documentos forem obsoletos e não confiáveis, os engenheiros não os lerão de qualquer maneira. A qualidade dos documentos determina a adoção.

Isso justifica o custo de uma ferramenta de documentação? Com os salários de engenharia sênior, recuperar mesmo duas horas por semana de tempo de foco em uma pequena equipe normalmente excede o custo de qualquer ferramenta de documentação no mercado. O cálculo do ROI é quase sempre positivo, e o benefício cresce com o tamanho da equipe.

Leitura relacionada: Por que documentos de engenharia importam, O custo de escrever documentos de engenharia, O custo oculto do conhecimento tribal. Páginas relacionadas: Documentos auto-escritos, Para equipes de engenharia.