A dívida de documentação se acumula mais rápido que a dívida técnica

Os engenheiros têm uma compreensão visceral da dívida técnica. Eles sabem como é trabalhar em uma base de código onde os atalhos se acumularam: cada um era racional na época, e o conjunto torna tudo mais difícil. Eles sabem que pagar a dívida técnica mais tarde é mais caro do que evitá-la em primeiro lugar, e sabem que ignorá-la por tempo suficiente acaba forçando uma reescrita.

A dívida de documentação funciona da mesma forma, com uma diferença importante: ela se acumula mais rápido porque ninguém a está acompanhando.

A dívida técnica é, pelo menos parcialmente, visível no próprio código. Um desenvolvedor lendo um módulo confuso pode sentir a dívida. Um revisor pode sinalizá-la. Um linter pode capturar parte dela. A dívida de documentação é invisível até que alguém precise da documentação ausente e descubra que ela não está lá, ponto em que o custo de criá-la retroativamente é muito maior do que o custo de criá-la em primeiro lugar teria sido.

Como ela se acumula

Cada PR enviado sem uma atualização de documentação correspondente adiciona um pequeno incremento de dívida de documentação. Cada decisão de arquitetura tomada em uma conversa do Slack que nunca é registrada em um documento permanente adiciona mais. Cada reunião onde prioridades são discutidas e o contexto é compartilhado verbalmente, mas nunca anotado, adiciona ainda mais.

Individualmente, cada uma delas parece insignificante. Coletivamente, ao longo dos meses, elas criam uma lacuna entre o que o sistema faz e o que qualquer pessoa fora dos desenvolvedores originais entende sobre ele. A lacuna cresce a cada sprint e, por ser invisível (nenhuma métrica a rastreia, nenhum painel a mostra), cresce sem que ninguém perceba, até que um evento desencadeador a torne dolorosamente aparente.

Os eventos desencadeadores são previsíveis: um novo contratado que leva meses para se tornar produtivo, um engenheiro-chave que sai e leva consigo um contexto crítico, um incidente de produção onde a resposta é lenta porque ninguém entende o sistema afetado o suficiente para diagnosticá-lo rapidamente, ou uma revisão de arquitetura onde a equipe descobre que está rediscutindo decisões que foram tomadas e resolvidas há um ano.

Por que ela se acumula mais rápido que a dívida técnica

A dívida técnica se acumula linearmente com as alterações de código. Cada atalho adiciona uma unidade de dívida. A dívida de documentação se acumula de forma composta, porque o valor da documentação é relacional: um documento sobre o Serviço A é mais útil quando se conecta a documentos sobre os Serviços B e C, e a ausência de qualquer um deles reduz o valor dos outros.

Quando a documentação de um sistema está ausente, a documentação dos sistemas que interagem com ele se torna menos útil, porque o leitor não consegue seguir as conexões. Quanto mais sistemas estiverem sem documentação, menos valor qualquer documento individual fornecerá, porque ele existe isoladamente, em vez de fazer parte de um cenário conectado.

Isso significa que a dívida de documentação não é apenas cumulativa. Cada incremento de dívida torna a documentação existente menos valiosa, o que faz com que o custo total da dívida cresça mais rápido do que a taxa em que a nova dívida é adicionada. Quando a dívida é grande o suficiente para ser perceptível, ela já é mais cara de pagar do que a maioria das equipes está disposta a investir, razão pela qual a resposta comum é aceitá-la e contorná-la, em vez de resolvê-la.

O ponto de inflexão do tamanho da equipe

A dívida de documentação é tolerável em equipes pequenas porque o conhecimento tácito serve como substituto: todo mundo sabe de tudo porque a tribo é pequena o suficiente. O ponto de inflexão geralmente ocorre entre dez e vinte engenheiros, que também é o momento em que a maioria das equipes começa a contratar rapidamente, e também o momento em que mais precisam de documentação e menos têm tempo para criá-la.

Esse momento é infeliz, mas previsível. O momento em que a equipe começa a crescer é o momento em que a documentação se torna essencial, e é também o momento em que a equipe existente está mais sobrecarregada e menos capaz de assumir o trabalho adicional de escrevê-la. A dívida de documentação que se acumulou nos primeiros dias, quando não importava muito, de repente se torna crítica, e pagá-la exige desviar o tempo de engenharia do trabalho em funcionalidades voltadas para o crescimento, impulsionado pelas novas contratações.

As equipes que gerenciam bem essa transição geralmente são aquelas que automatizam a documentação antes do ponto de inflexão, e não depois, para que os documentos cresçam junto com a equipe, em vez de ficarem para trás.

Perguntas frequentes

Como medimos a dívida de documentação? Métricas indiretas: tempo de integração de um novo engenheiro, número de perguntas feitas no Slack que seriam respondidas pela documentação existente se ela existisse, frequência de decisões rediscutidas e tempo para resolver incidentes de produção em sistemas com versus sem documentação. Nenhuma delas mede a dívida de documentação diretamente, mas juntas indicam o seu tamanho.

Devemos fazer um sprint de documentação? Um sprint de documentação reduz o acúmulo, mas sem uma mudança na forma como as documentações são criadas continuamente, a dívida se acumulará novamente de imediato. Pense nisso como declarar falência: limpa o histórico, mas não muda os hábitos de consumo. A solução estrutural é uma documentação que se gera sozinha a partir das atividades contínuas de engenharia.

Com qual tamanho de equipe isso se torna crítico? A maioria das equipes sente isso entre 10 e 20 engenheiros, mas a dívida começa a se acumular desde o primeiro dia. O melhor momento para abordá-la é antes de senti-la, porque o custo da prevenção é uma fração do custo da cura.

Leitura relacionada: Por que a documentação de engenharia importa, Documentos desatualizados são piores do que nenhum documento, O paradoxo da documentação. Páginas relacionadas: Documentos que escrevem a si mesmos, Para equipes de engenharia.