Documentações desatualizadas são piores do que nenhuma documentação

Uma equipe sem documentação sabe que não tem documentação. Os engenheiros fazem perguntas, interrompem colegas e reconstroem o contexto verbalmente. É ineficiente, mas pelo menos todos conhecem a situação.

Uma equipe com documentação desatualizada tem um problema diferente. Os documentos existem, parecem autoritativos e estão errados. Um engenheiro segue o guia de configuração e perde uma tarde inteira porque o guia faz referência a uma dependência que foi substituída há três meses. Outro engenheiro lê a visão geral da arquitetura, toma uma decisão de design baseada nela e descobre durante a revisão de código que a visão geral descreve um sistema que foi reestruturado no último trimestre.

Após duas ou três dessas experiências, o engenheiro deixa de confiar nos documentos. Eles voltam a perguntar diretamente às pessoas, que é o que teriam feito se não houvesse documentação alguma. Mas agora a equipe está pagando o custo de manter documentos que ninguém lê, além do custo da transferência verbal de conhecimento que os documentos deveriam eliminar.

Este é o paradoxo da documentação em sua forma mais prejudicial: o investimento em documentação produziu retornos negativos porque os documentos ativamente desorientam, em vez de estarem simplesmente ausentes.

Como a documentação fica obsoleta

A documentação não apodrece porque os engenheiros são descuidados. Ela apodrece porque cada PR mesclado torna os documentos existentes ligeiramente menos precisos, e o trabalho de correção nunca é priorizado.

Uma refatoração altera a forma como dois serviços se comunicam. O engenheiro atualiza o código, escreve testes, obtém o PR revisado e mesclado. Atualizar as três páginas wiki que descrevem o antigo padrão de comunicação não faz parte do checklist do PR e não faz parte do sprint. Ninguém atribui essa tarefa porque ninguém está monitorando quais documentos são afetados por quais alterações de código. As páginas wiki ficam lá, descrevendo um sistema que não existe mais, esperando que alguém as siga e falhe.

A taxa de obsolescência correlaciona-se diretamente com a velocidade de entrega. Quanto mais rápido você entrega, mais rápido seus documentos ficam desatualizados, o que significa que as equipes que mais precisam de documentação confiável (bases de código em rápida evolução e movimento rápido) são aquelas cujos documentos apodrecem mais rápido.

O problema da confiança

A confiança na documentação, uma vez perdida, é extremamente difícil de reconstruir. São necessárias dezenas de consultas a documentos precisos e úteis para criar o hábito de verificar os documentos primeiro. São necessárias apenas uma ou duas experiências enganosas para quebrá-lo.

Uma vez que uma equipe de engenharia tenha aprendido coletivamente que os documentos não são confiáveis, eles se tornam invisíveis. Os novos contratados são informados informalmente de que a wiki está "na maior parte desatualizada" e que devem perguntar em vez de ler. Os documentos ainda existem, ainda aparecem nos resultados de pesquisa, ainda parecem oficiais, mas foram funcionalmente abandonados. Cada hora gasta escrevendo-os foi desperdiçada.

A única documentação que evita esse problema é a documentação que se mantém atualizada automaticamente. Documentos autoescritos gerados a partir da atividade de engenharia em tempo real (PRs, canais do Slack, gravações de reuniões) são atualizados à medida que a atividade subjacente muda. Os documentos refletem a realidade porque são escritos a partir da realidade, em vez de serem mantidos paralelamente a ela.

A questão da auditoria

Existe um teste simples para saber se seus documentos têm esse problema. Escolha uma página wiki aleatória ou um documento de arquitetura que tenha sido atualizado pela última vez há mais de três meses. Leia-o. Em seguida, pergunte ao engenheiro que atualmente é o proprietário desse sistema se o documento ainda está correto.

Na maioria das equipes, a resposta é alguma variação de "partes dele estão certas, mas alguns detalhes mudaram". Esses detalhes são os que farão o próximo engenheiro perder a tarde inteira.

Perguntas frequentes

Devemos simplesmente excluir documentos obsoletos? Excluir documentos claramente desatualizados é melhor do que deixá-los desorientando as pessoas. Mas a melhor solução é evitar a obsolescência em vez de limpar a bagunça depois. Documentos que se escrevem sozinhos a partir de fontes em tempo real não ficam obsoletos da mesma forma porque se atualizam conforme a atividade subjacente muda.

Como sabemos quais documentos estão obsoletos? Monitore quando os documentos foram atualizados pela última vez em relação a quando os sistemas que eles descrevem foram alterados pela última vez. Se um documento sobre o fluxo de autenticação foi editado pela última vez em janeiro e o serviço de autenticação teve 40 PRs desde então, o documento está quase certamente obsoleto.

Vale a pena manter a documentação manualmente se entregamos rápido? Quanto mais rápido você entrega, mais rápido os documentos manuais apodrecem, o que significa que o ROI da documentação manual diminui à medida que a velocidade de entrega aumenta. Para equipes ágeis, a documentação automatizada é a única abordagem que consegue acompanhar o ritmo.

Leitura recomendada: O paradoxo da documentação, Dívida de documentação, Por que os engenheiros odeiam escrever documentação. Páginas relacionadas: Documentação autoescrita, Para equipes de engenharia.