Por que a documentação de engenharia importa mais do que os engenheiros pensam

A maioria das equipes de engenharia tem um relacionamento complicado com a documentação. Todos concordam que ela é importante. Quase ninguém a prioriza. O backlog de recursos a serem entregues sempre parece mais urgente do que o backlog de decisões a serem documentadas, e o resultado é uma base de código que cresce constantemente enquanto a compreensão de por que ela foi construída daquela forma se desgasta no mesmo ritmo.

Isso não é preguiça. É uma resposta racional a estruturas de incentivo que recompensam a entrega de código e não recompensam a escrita sobre ele. Mas os custos decorrentes de uma documentação ruim são reais, mensuráveis e muito maiores do que a maioria das equipes imagina, e eles se acumulam de maneiras que se tornam mais difíceis de resolver quanto mais tempo são ignorados.

As quatro funções da documentação

A documentação de engenharia atende a quatro funções distintas, e a maioria das equipes só pensa em uma delas.

Reduzir erros. Quando o raciocínio por trás de uma decisão de arquitetura é documentado, os engenheiros que mexem nesse sistema mais tarde entendem por que ele foi construído daquela maneira e quais restrições precisam respeitar. Sem esse contexto, eles fazem alterações que parecem razoáveis isoladamente, mas que quebram premissas nas quais o autor original confiava. O resultado são bugs difíceis de diagnosticar porque a quebra é conceitual, não sintática. O código funciona bem. Ele apenas faz a coisa errada.

A documentação de decisões, o registro de por que uma abordagem específica foi escolhida e quais alternativas foram consideradas, é a camada que falta na maioria das equipes. Os comentários no código explicam o que o código faz. Os documentos de decisão explicam por que ele existe desta forma e não de outra. Sem o porquê, cada decisão arquitetônica é rediscutida por cada novo engenheiro que a encontra.

Acelerar a integração (onboarding). Um novo engenheiro que entra em uma equipe bem documentada pode se orientar pela leitura. Ele consegue entender a arquitetura do sistema, as principais decisões, as convenções e o estado atual dos projetos ativos antes de escrever uma única linha de código. Um novo engenheiro que entra em uma equipe mal documentada precisa reconstruir tudo isso por meio de conversas, o que significa interromper as pessoas que deveriam estar entregando código.

A diferença no tempo de ramp-up é tipicamente de semanas, não de dias, e o custo dessas semanas é medido tanto no salário improdutivo da nova contratação quanto na produtividade interrompida dos engenheiros seniores.

Preservar o conhecimento institucional. As pessoas saem. Elas mudam de equipe, mudam de empresa, entram em licença-maternidade/paternidade, são promovidas para cargos onde não mexem mais no código. Cada partida leva conhecimento embora, e o conhecimento que sai é tipicamente o de maior valor: o contexto, o raciocínio, o histórico de por que as coisas são do jeito que são.

A documentação é o mecanismo que converte o conhecimento pessoal em conhecimento organizacional, o que significa que a organização retém o que aprendeu mesmo quando as pessoas que aprenderam seguem em frente. Sem documentação, a organização está perpetuamente reaprendendo coisas que já sabia, o que é uma das formas mais caras de desperdício na engenharia.

Habilitar ferramentas de IA. Esta é a função que surgiu mais recentemente e pode se tornar a mais importante. Toda ferramenta de IA no seu fluxo de trabalho de engenharia, desde assistentes de código a agentes internos e sistemas de documentação autoescrita, tem um desempenho melhor com mais contexto. Se o seu conhecimento de engenharia vive em canais do Slack e na cabeça das pessoas, suas ferramentas de IA não conseguem acessá-lo. A documentação é o que torna a IA útil no seu contexto organizacional específico, em vez de apenas genericamente capaz.

Por que os documentos continuam perdendo para os recursos

Entender por que a documentação é importante não explica por que ela continua sem ser feita. A resposta é estrutural, não cultural.

A documentação cria um valor difuso e de longo prazo (menos bugs no próximo trimestre, integração mais rápida na próxima contratação, conhecimento preservado na próxima partida), enquanto a entrega de recursos cria um valor concentrado e imediato (solicitação de cliente atendida, receita liberada, stakeholder satisfeito). Em qualquer estrutura de priorização que pondere urgência e visibilidade, os recursos vencerão todas as vezes, porque o custo de documentos ausentes é invisível até que cause um problema específico e rastreável, que a essa altura está a meses de distância da decisão de não documentar.

Os engenheiros também sabem, corretamente, que os documentos ficam desatualizados. O paradoxo da documentação é que cada PR mesclado após a redação dos documentos torna esses documentos um pouco menos precisos. Escrever documentos que você sabe que estarão desatualizados em poucas semanas parece uma proposta perdedora, e para documentações mantidas manualmente, realmente é.

É por isso que a resposta para o problema da documentação é arquitetônica, não motivacional. Dizer aos engenheiros para escreverem mais documentos não funciona porque a estrutura de incentivos é contra isso. Remover totalmente os engenheiros do ciclo de documentação, gerando e mantendo documentos automaticamente a partir da atividade de engenharia que já está acontecendo (PRs, conversas no Slack, reuniões, commits), muda completamente essa lógica econômica. Os documentos permanecem atualizados porque são escritos a partir da origem, em vez de mantidos manualmente.

O custo acumulado de ignorar a documentação

Os custos de uma documentação ruim se acumulam da mesma forma que a dívida de documentação se acumula: de forma silenciosa, cumulativa e mais rápida do que a maioria das equipes espera.

Em uma equipe de cinco pessoas, todo mundo sabe tudo. Todo o sistema cabe na cabeça de algumas pessoas, e o conhecimento informal funciona porque o grupo é pequeno. Com dez pessoas, começam a surgir lacunas. Com vinte, as lacunas estão atrasando as coisas visivelmente. Com cinquenta, o gargalo do conhecimento informal é uma das principais restrições na velocidade de entrega, porque cada decisão que requer contexto exige uma reunião ou uma conversa no Slack para reconstruir o contexto que nunca foi documentado.

As equipes que investem em documentação desde cedo raramente se arrependem. As equipes que adiam isso até que a dor se torne aguda descobrem que o custo de documentar retroativamente um sistema grande e complexo é muito maior do que o custo de documentá-lo à medida que era construído. Assim como a dívida técnica, a dívida de documentação é mais barata de prevenir do que de corrigir.

Perguntas frequentes

O que deve ser documentado primeiro? Decisões de arquitetura, limites do sistema e guias de integração. Estes têm o maior retorno porque resolvem os problemas mais caros: erros por incompreensão da arquitetura, integração lenta e perda de conhecimento quando as pessoas saem.

Como fazemos os engenheiros escreverem documentos? Idealmente, você não faz. A abordagem mais sustentável é a documentação que se escreve sozinha a partir da atividade de engenharia que já está acontecendo. Se isso não for possível, dedique tempo explicitamente (sprints de documentação, dias de doc) e torne a qualidade da documentação visível nas revisões.

A documentação de código (comentários, READMEs) é suficiente? A documentação de código explica o que o código faz. Ela não explica por que foi construído daquela forma, quais alternativas foram consideradas ou como diferentes sistemas se relacionam entre si. Ambas as camadas são necessárias, mas a camada de decisão e arquitetura é tipicamente a que está faltando.

Leituras relacionadas: O custo de escrever documentos de engenharia, Dívida de documentação, Por que os engenheiros odeiam escrever documentos, Explicação sobre documentos autoescritos. Páginas relacionadas: Documentação autoescrita, Para equipes de engenharia, Retenção de conhecimento.