O paradoxo da documentação: cada PR torna seus documentos menos precisos

Aqui está o problema fundamental da documentação de engenharia: no momento em que você a escreve, ela começa a se tornar menos verdadeira.

Uma página de wiki descreve com precisão a arquitetura do serviço de pagamento no dia em que é escrita. Na semana seguinte, um PR reestrutura a lógica de repetição. Na semana seguinte, outro PR adiciona uma nova integração de provedor de pagamento. Um mês depois, uma refatoração consolida dois módulos em um só. Nenhuma dessas mudanças atualiza a página da wiki, porque não há conexão entre o código e a documentação. Cada PR torna a documentação um pouco menos precisa, e o desvio acelera com a velocidade de entrega.

Este é o paradoxo da documentação: quanto mais rápido sua equipe entrega, mais rápido sua documentação fica desatualizada, o que significa que as equipes que mais precisam de documentação confiável são aquelas cuja documentação se deteriora mais rapidamente. A documentação manual é uma corrida contra sua própria velocidade, e é uma corrida que você não pode vencer porque a documentação está sempre um passo atrás do código.

Por que a manutenção manual falha

A resposta padrão para documentações desatualizadas é um processo de manutenção: atribuir responsáveis, agendar ciclos de revisão, adicionar atualizações de documentação às listas de verificação de PR. Esses processos ajudam na margem, mas todos dependem da disciplina humana, que se degrada exatamente sob as condições em que a documentação é mais importante.

Quando a equipe está entregando rápido sob a pressão de prazos ou lidando com um incidente, a manutenção da documentação é a primeira coisa a ser despriorizada. Os revisores de PR deixam de verificar se a documentação foi atualizada. Os responsáveis pelas páginas da wiki ficam atrasados em seus ciclos de revisão. O processo de manutenção funciona quando as coisas estão calmas e falha quando as coisas estão intensas, o que significa que funciona menos quando é mais necessário.

O outro problema é que ninguém sabe quais documentos são afetados por uma determinada alteração de código. Uma refatoração pode invalidar três páginas de wiki, dois diagramas de arquitetura e um guia de integração (onboarding), e o engenheiro que faz a alteração não tem como saber quais documentos fazem referência ao componente que está modificando. Mesmo um engenheiro consciencioso que queira atualizar a documentação não consegue fazer isso de forma confiável porque o mapeamento entre o código e a documentação não tem manutenção e, muitas vezes, é inexistente.

A solução arquitetônica

A única documentação que acompanha o ritmo de uma base de código em rápida evolução é aquela que se atualiza a partir das mesmas fontes que alteram o código.

Documentação escrita automaticamente (self-writing) resolve o paradoxo ao gerar documentos a partir da atividade de engenharia em tempo real. Quando um PR altera a forma como dois serviços se comunicam, a documentação sobre essa comunicação é atualizada para refletir a alteração. Quando uma conversa no Slack discute e resolve uma questão de design, os documentos relevantes incorporam a decisão. Quando uma reunião aborda um plano de migração, a documentação reflete o plano atual, em vez daquele de três meses atrás.

Os documentos permanecem atualizados porque são escritos a partir das mesmas fontes que alteram o sistema. Não há lacuna entre o código e a documentação porque a documentação é derivada da atividade do código, em vez de ser mantida em paralelo a ele.

Os engenheiros ainda revisam e refinam os documentos gerados, mas a precisão de base é mantida automaticamente, o que significa que a revisão é uma etapa de garantia de qualidade, e não um exercício de reescrita. O paradoxo é resolvido porque a documentação não precisa ser mantida manualmente em sincronia com um alvo em movimento. Ela se move junto com ele.

Perguntas frequentes

Com que rapidez a documentação mantida manualmente fica desatualizada? Em equipes que se movem rapidamente, imprecisões significativas podem surgir poucas semanas após a redação de um documento. Um documento de três meses de idade em uma base de código com desenvolvimento ativo normalmente não é confiável em detalhes, mesmo que as diretrizes gerais ainda estejam corretas.

Podemos apenas marcar os documentos com uma data de "última verificação"? Isso é melhor do que nada porque dá ao leitor um sinal sobre o quanto confiar no conteúdo. Mas não resolve o problema subjacente: alguém ainda precisa verificar o documento, e essa verificação exige entender quais alterações de código podem tê-lo invalidado.

Isso é um problema para todos os tipos de documentação? É pior para documentação que descreve detalhes de implementação, arquitetura de sistemas e pontos de integração, pois estes mudam com mais frequência. A documentação conceitual (por que usamos microsserviços, nossa filosofia de testes) é mais durável porque as decisões subjacentes mudam com menos frequência.

Leitura relacionada: Documentos desatualizados são piores do que nenhum documento, Débito de documentação, Documentação autodocumentável explicada. Páginas relacionadas: Documentos autodocumentáveis, Para equipes de engenharia.