Por que a documentação sempre perde para a realidade
Por que a documentação sempre perde para a realidade, como a IA torna o problema insustentável, e o que vem depois do artefato.
Acontece mais ou menos assim. Você encontra um erro e precisa de uma resposta. Procura primeiro na base de conhecimento (wiki), acha a página certa, encontra um rascunho de 2022 que não bate direito. Vai para o Slack, rolando threads antigas de pessoas que já saíram da empresa há anos. Abre o código esperando inferir a resposta na fonte. No fim, você desiste e pergunta no canal #suporte. Horas se passaram.
Essa é a experiência universal de trabalhar em um sistema complexo, e tem sido assim desde que software tem documentação. Qualquer documento isolado pode estar perfeitamente em ordem. Mesmo assim, a documentação como um todo acaba sendo menos confiável do que perguntar para um engenheiro sênior no Slack. Quando isso é mais fácil do que usar a documentação, a documentação já perdeu.
A explicação padrão é um problema de disciplina. As pessoas não atualizam a documentação. Os times não priorizam. A liderança não cobra. Essa história se repete há décadas, e a receita também. Escrever mais, escrever melhor, escrever mais cedo, escrever junto, escrever conforme o padrão. Nada disso mudou o resultado.
Então talvez o diagnóstico esteja errado.
A falha é estrutural
Tentar mais não funcionou. Já tentamos escrever em wikis, depois no Confluence, depois no Notion. Já tentamos docs-as-code, controle de versão para documentação, ciclos de revisão trimestrais, donos de documentação com responsabilidade explícita. Já tentamos contratar "technical writers". Já tentamos exigir atualizações como parte da definition-of-done. Cada nova ferramenta prometeu uma melhoria estrutural e entregou uma melhoria de disciplina. Cada uma se desgastou no mesmo ritmo.
A falha vive uma camada abaixo, no próprio artefato, além do alcance da disciplina.
Em um post anterior, argumentei que dados são um artefato: algo escrito por alguém, em algum lugar, sob condições que faziam sentido na época. Tire as condições iniciais e você fica adivinhando. A mesma lógica se aplica à documentação. Uma página de wiki é um artefato. Uma spec OpenAPI também, assim como um ADR. Cada um é um snapshot tirado sob condições que já mudaram, e sob suposições sobre os consumidores que nunca foram completas. Uma página pode descrever o sistema, mas não pode ser o sistema. Essa lacuna é estrutural.
A autogeração está resolvendo o problema errado
A solução óbvia é tirar humanos do loop. Documentação escrita por pessoas é sempre atrasada por natureza. Gere a partir do código quase em tempo real, faça type-check, rode no CI. Specs OpenAPI, JSDoc, Mintlify, Stoplight. Páginas e páginas de ferramentas existem exatamente para isso. O artefato fica atualizado com o código fonte porque a fonte deveria ser a fonte da verdade (veja "Code as Documentation" de Martin Fowler).
Mas a realidade continua se movendo mesmo assim.
Um time lança um endpoint de busca com uma spec OpenAPI limpa: query de entrada, lista de resultados de saída. A spec não diz o que acontece quando há zero resultados. A implementação retorna uma lista vazia. O frontend começa a iterar sobre results sem condicional. Seis meses depois, uma otimização do backend omite o campo results inteiro quando não há correspondências. A spec não muda. O frontend começa a lançar undefined.length em produção. Ninguém especificou o formato do array vazio porque ninguém pensou que era uma decisão. A spec, recém-regenerada na noite anterior, ainda descreve um contrato que não foi quebrado.
A Lei de Hyrum explica a dinâmica:
Com um número suficiente de usuários de uma API, não importa o que você promete no contrato: alguém vai acabar dependendo de todos os comportamentos observáveis do seu sistema.
A Lei de Hyrum foi escrita sobre estabilidade de APIs, mas diagnostica um problema mais amplo. Uma especificação registra o comportamento que um autor achou importante escrever. O sistema tem mais comportamento do que isso, e os consumidores se acoplam a tudo. Nenhuma quantidade de geração fecha essa lacuna, porque a lacuna não é um problema de atualização.
A spec captura o que o autor escolheu especificar. Os consumidores dependem de comportamentos que a spec nunca iria enumerar. Envelopes de erro, tempos de resposta, ordenação, suposições comportamentais que nunca foram escritas na spec. Schema registries e contract tests ajudam. Eles não conseguem fechar a lacuna, porque os consumidores acabam dependendo de muito mais do que qualquer um pensou em registrar.
O código fica. O que muda é o significado atrelado a ele, e a fronteira da qual os consumidores de fato dependem. O mesmo nome de campo, o mesmo endpoint, a mesma assinatura aponta para coisas diferentes em momentos diferentes. A autogeração fecha a lacuna de atualização e deixa a lacuna de significado intocada.
Capturando o porquê
Talvez a questão mais profunda seja que a documentação captura o o quê mas não diz nada sobre o porquê. Uma página de wiki te diz o estado atual de um sistema. Não te diz por que o sistema é construído da forma que é, o que o time estava resolvendo, quais trade-offs aceitaram.
Architecture Decision Records (ADR - propostos por Michael Nygard em 2011) existem exatamente para resolver isso. Capturar a decisão, seu contexto, e o que mudaria a sua opinião. O design original também lida com mudança corretamente: um ADR aceito nunca é editado; é substituído por um ADR posterior que linka de volta a ele. A cadeia forma um log de qual decisão governou qual período.
Então, se capturamos o estado em wikis e as decisões (transições de estado) em ADRs, estamos totalmente cobertos?
Na prática, o formato se desgasta. Pureur e Bittner descrevem como ADRs degradam em "Any Decision Records" quando os times registram todas as decisões como arquiteturais. A solução proposta é taxonômica: tipos diferentes de registros para tipos diferentes de decisões, para que os arquiteturais fiquem distintos.
Per Møller Zanchetta vai além. Ele argumenta que ADRs falham quando os times os tratam como documentação em vez de infraestrutura. "Documentação captura o que já aconteceu; infraestrutura molda o que acontece em seguida." A solução proposta é embutir ADRs em controle de versão, revisões de PR e rituais de sprint, tratando-os como o meio em que as decisões são tomadas, e não como artefatos a serem consultados depois.
As duas críticas estão certas sobre os sintomas. Mas perdem a força mais profunda: a arquitetura se acumula, com ou sem os seus registros.
ADRs documentam as decisões conscientes: os momentos em que um time pausou, pesou alternativas e escolheu. O custo dessa cerimônia é real, e os times reservam isso para decisões que parecem arquiteturais na hora.
Um time adiciona um checkbox "lembrar de mim" no formulário de login. Ele contorna o fluxo padrão de refresh-token porque o PM quer sessões de trinta dias e o fluxo padrão expira em 24 horas. Sem ADR; a mudança parece um ajuste de UX. Dezoito meses depois, três outras features foram construídas sobre a suposição de 24 horas. Uma regra de detecção de fraude que aciona pela frequência de re-autenticação começa a sinalizar a coorte de sessão longa como suspeita. Ninguém liga os pontos até um engenheiro de suporte perceber os mesmos IDs de usuário em três tickets não relacionados. A cadeia de ADR ainda descreve um sistema de autenticação que não existe mais. A mudança estava abaixo do limite de ADR. Seu efeito acumulado foi arquitetural.
Alguém vai dizer: isso deveria ter sido um ADR. Mas o limite é exatamente o que faz ADRs funcionarem. Abaixe-o, e você tem a confusão dos "Any Decision Records" que Pureur e Bittner descreveram. Mantenha-o, e a arquitetura que emerge abaixo dele é invisível por construção. O formato está fazendo exatamente o que foi projetado para fazer, e a arquitetura se acumula mesmo assim.
A IA piora o problema
O CEO da Klarna, Sebastian Siemiatkowski, nomeou esse problema recentemente. Em um podcast recente do 20VC, ele disse algo que a maioria dos times vive mas não fala em voz alta:
Agentes de atendimento ao cliente (...) precisam de tanto contexto quanto possível. Mas onde está esse contexto? Está no código-fonte do seu software (...) Podemos ter documentação disso, mas, na verdade, está em algum lugar profundo no nosso código-fonte (...) e a documentação pode estar imprecisa. Então você percebe que mais cedo ou mais tarde um agente de atendimento ao cliente precisa ler o código-fonte para conseguir responder uma pergunta. (Tradução livre)
A conclusão dele foi operacional. Um agente de atendimento ao cliente, humano ou IA, mais cedo ou mais tarde tem que ler o código-fonte para responder com precisão. A Klarna não conseguiu comprar uma solução pronta e construiu a sua. Uma fintech multibilionária com todas as razões para fazer a documentação funcionar, declarando publicamente que a verdade vive no código-fonte. Se nem a Klarna, com todo o recurso que tem, fechou a lacuna, a maioria das empresas não vai conseguir.
Para humanos, documentação desatualizada sempre foi cara, mas limitada. Um engenheiro perde uma tarde, aprende a desconfiar da documentação interna e pergunta a um engenheiro sênior. Engenheiros sêniores se tornam o gargalo de conhecimento e os times constroem conhecimento tribal para preencher a lacuna. A produtividade cai, mas a empresa não desaba.
Para os agentes, o modo de falha muda. Agentes leem em velocidade de máquina e não têm um engenheiro sênior para perguntar. Mesmo quando são conservadores e detalhistas, só conseguem verificar contra a especificação documentada, e os comportamentos que causam estrago vivem fora dela. Uma página de wiki desatualizada que custou a um humano uma tarde lenta custa a um agente uma decisão errada em produção. Mesmo modo de falha, em um nível de impacto totalmente diferente.
A assimetria é o que vira sustentação. Humanos toleram artefatos desatualizados porque interpretam e checam duas vezes. Agentes não. Eles se comprometem com o que estiver na frente deles em velocidade de máquina.
O sistema tem o contexto
Documentação e dados compartilham o mesmo modo de falha. São artefatos escritos uma vez, encarregados de acompanhar um sistema que continua se movendo, mas nunca realmente conseguiram. Agora os agentes estão lendo esses artefatos em velocidade de máquina e agindo sobre eles.
A mudança está em onde o contexto vive. O próprio sistema tem o contexto. A documentação sempre foi uma descrição paralela tentando acompanhá-lo de fora.
O leitor mudou. Onde um humano consultava uma página e raciocinava apesar das lacunas, um agente consulta o sistema diretamente.
Um sistema que carrega seu próprio contexto expõe aquilo de que os consumidores realmente dependem. Schemas vivos que você pode introspectar, endpoints de runtime que reportam quais comportamentos estão em vigor no momento, MCP servers que deixam um agente perguntar ao sistema rodando o que ele faz em vez do que alguém escreveu uma vez. O caso do array vazio, lá no começo, deixa de ser uma pergunta para a spec; o agente consulta o serviço e vê o formato atual. A mudança do "lembrar de mim" deixa um rastro na mesma superfície que o próximo agente vai ler.
A pergunta muda de forma fundamental. Em vez de perguntar "o que a documentação diz sobre isso?", o consumidor passa a perguntar "o que o sistema faz agora?". O sistema fica consultável não só pelo estado atual, mas pelo comportamento que está em vigor, pelas suposições que carrega, e por quem depende delas.
Na prática, isso significa coisas como: um time pergunta ao serviço de pagamentos qual schema ele retorna agora e recebe a resposta direto, sem precisar confiar na spec. Um agente, antes de agir sobre um endpoint, descobre quais consumidores dependem de qual variação do contrato. Uma equipe que vai depreciar um campo vê quem está usando aquele campo em produção, em tempo real.
Isso não aposenta o wiki. Onboarding, narrativa, explicações conceituais ainda devem ser escritas por pessoas. A camada de sustentação que está embaixo muda. O artefato deixa de ser solicitado para rastrear o que o sistema faz, porque o sistema pode responder por si mesmo.
Este é um dos insights que me motivou a criar a Dipolo AI. Se você já viu a documentação perder para a realidade mais vezes do que gostaria de admitir, adoraria conversar. Me mande uma mensagem: raphael@dipolo.ai.