Sua documentação apodreceu no instante em que você fez o merge

Uma função foi renomeada numa terça-feira. O README ainda a chama pelo nome antigo. O doc de onboarding ainda mostra a assinatura antiga. O runbook ainda diz ao engenheiro de plantão para rodar uma flag que não existe mais. Ninguém tocou em nenhum desses três arquivos, e esse é o ponto. Eles não mudaram. O código abaixo deles mudou. Então eles pararam de ser verdade no segundo em que o pull request fez merge, e nem uma pessoa percebeu.

Esse intervalo, entre o código que se mexeu e o doc que não, é onde a documentação vai apodrecer.

Tendemos a falar de docs desatualizados como um problema de disciplina, como se a cura fosse uma regra mais rígida: sempre atualize os docs quando você mudar o código. Não é um problema de disciplina. É um problema de timing. O doc não ficou errado porque alguém foi preguiçoso. Ele ficou errado porque nada estava observando o diff no momento em que o diff aconteceu. A correção não é uma regra. É um observador.

Docs apodrecem na velocidade do código, e uma regra não os salva

Aqui está o modelo ingênuo, o que todo time começa adotando. Documentação é algo que você escreve uma vez e atualiza “quando necessário”. Você a mantém ao lado do código, pede às pessoas que sejam bons cidadãos, e confia que um engenheiro cuidadoso que renomeia uma função também vai consertar o README, o doc de arquitetura, e os quatro guias que a mencionam.

Funciona por cerca de uma semana. Depois não funciona, e a razão é estrutural, não moral.

Código muda constantemente e em incrementos minúsculos. Um doc é um instantâneo. Cada commit empurra o código um pouco mais longe do instantâneo, e ninguém consegue ver a deriva porque a deriva é invisível, o doc ainda renderiza, ainda lê bem, ainda parece pronto. Um doc errado e um doc certo são idênticos pixel por pixel até alguém confiar no errado. Não há um sublinhado vermelho embaixo de uma frase que costumava ser verdade. O compilador não se importa. Os testes não se importam. Prosa não tem type system.

Então o intervalo se alarga silenciosamente, e o custo aterrissa depois, em alguém que não estava lá. O novo contratado que segue o guia de setup direto para uma parede. O engenheiro de plantão que roda o comando documentado às 3 da manhã e o vê falhar. O colega que constrói contra uma API que o doc prometeu e o código não oferece mais. Cada um deles paga por uma mudança que não fez, porque o doc que deveria tê-los avisado estava silenciosamente errado.

A regra, “atualize os docs”, falha pela mesma razão que todas as regras de bom-cidadão falham. Ela pede a um humano cansado, no meio de uma tarefa, que lembre de um segundo trabalho que não tem prazo nem alarme. O doc não ficou errado porque alguém esqueceu. Ele ficou errado porque nada estava observando o diff.

Essa frase é a tese inteira, então vamos dizê-la com clareza e depois construir a máquina que a torna falsa.

O observador lê o diff, não o calendário

O instinto óbvio, uma vez que você admite que a regra não te salvará, é agendar uma auditoria. Uma vez por trimestre, alguém lê a pasta inteira de docs e conserta o que está desatualizado. Isso é melhor que nada e pior do que soa.

Uma auditoria de calendário é o relógio errado. Ela dispara numa data, mas docs não apodrecem numa data, eles apodrecem num commit. Quando a revisão trimestral chega, a deriva já está no ar há semanas, o novo contratado já bateu na parede, e o revisor está tentando reconstruir qual dos duzentos commits quebrou qual dos cinquenta docs. Você está pedindo a um humano que faça o diff de três meses de código contra uma pasta de prosa, de memória, numa tarde. Ninguém faz isso bem. Na maioria das vezes, ninguém faz.

O relógio certo é o próprio diff. No momento em que uma mudança aterrissa, esse é o momento de perguntar: isso acabou de tornar um doc errado? Não em três meses. Agora, enquanto o autor ainda tem a mudança na cabeça e o custo de consertar o doc é mais uma linha no mesmo pull request em vez de um projeto de arqueologia no próximo trimestre.

Então o observador não roda num cronograma. Ele roda em cada mudança. Quando um pull request mexe numa função, numa flag, numa chave de config, num endpoint, numa mensagem de erro, o observador lê esse diff e faz uma pergunta estreita à documentação: alguma coisa que escrevemos ainda afirma que a coisa antiga é verdade?

A ideia central é simples, então vamos nomear o que a faz funcionar. O observador não é “uma IA que escreve docs”. É um agent apontado para duas coisas de uma vez, a mudança e o corpus do que você já escreveu, cujo trabalho inteiro é encontrar a contradição entre elas. Ele já sabe que o README menciona a função, porque consegue ler o README. Ele consegue ver que a função foi renomeada, porque consegue ler o diff. O casamento é o alerta. Este arquivo diz chargeCustomer. Este commit deletou chargeCustomer. Olhe aqui.

Essa é a diferença entre um observador e uma auditoria. A auditoria caça através de tudo torcendo para encontrar a deriva. O observador recebe a mudança exata e só precisa perguntar o que aquela única mudança quebrou. O espaço de busca colapsa de “a pasta inteira de docs” para “o punhado de docs que mencionam a coisa que acabou de se mexer”. Pergunta pequena, respondida agora, pela única parte que consegue ver os dois lados do intervalo no mesmo momento.

Sinalize, não autocorrija, o humano fica com a caneta

Há um exagero tentador aqui, e vale a pena recusá-lo em voz alta, porque é a versão que a maioria das pessoas imagina quando ouve “um agent que conserta seus docs”.

O exagero é: deixar o agent reescrever o doc automaticamente. Ele vê a renomeação, corrige o README, faz o commit do conserto, pronto. Limpo, autônomo, e errado de um jeito difícil de ver até morder.

O problema é que um doc carrega intenção, não só fatos. A função foi renomeada, ok, o observador pode trocar o nome. Mas por que ela foi renomeada? Talvez o novo nome sinalize um novo contrato, uma nova ressalva, uma mudança de comportamento que a frase antiga ao redor não descreve mais. Um agent que mecanicamente troca o identificador produz um doc que agora está sintaticamente atual e semanticamente mentindo, o que é estritamente pior que um doc desatualizado, porque um doc desatualizado ao menos anuncia sua idade ao mencionar um nome que não existe mais. Um doc autocorrigido silenciosamente parece fresco e lê errado, e agora ninguém o está observando porque o observador já “cuidou” dele.

Então o observador não autocorrige. Ele sinaliza. Ele diz, no pull request, na frente do humano que fez a mudança: este README referencia a função que você acabou de renomear; este guia mostra uma flag que você acabou de remover; esta nota de arquitetura descreve um fluxo que você acabou de redirecionar. Ele aponta para o intervalo. Ele pode rascunhar um conserto sugerido. Mas a caneta fica na mão do humano, porque o humano é quem sabe se a renomeação foi cosmética ou estrutural.

Essa é a mesma disciplina que um bom agent usa em todo lugar na Apollo. A máquina faz a observação, a parte incansável, tediosa, de cobertura 100% em que humanos são estruturalmente ruins. O humano faz a decisão, o juízo sobre o que a mudança significa, que é a parte que sempre foi o trabalho de verdade. O observador transforma “lembre de checar cinquenta docs” em “aprove ou edite três sugestões, bem aqui, com a mudança ainda quente”. Ele move o custo de depois-e-caro para agora-e-barato, e nunca move a autoria.

Há um benefício mais silencioso, também. Como o sinalizador aterrissa no pull request, o conserto do doc e a mudança de código embarcam juntos, são revisados juntos, pela mesma pessoa que entende ambos. O doc para de ser uma tarefa separada que mora num backlog separado e passa a ser uma propriedade da mudança, tão inseparável do merge quanto os testes são.

Por que “jardinagem” é a palavra certa, e “escrever” é a errada

As pessoas perguntam se um agent consegue escrever a documentação delas, e essa é a pergunta errada, porque escrever nunca foi a parte cara. Qualquer um consegue escrever um doc. Um modelo certamente consegue rascunhar um. A parte cara, a parte que falência todo esforço de documentação eventualmente, é manter um doc verdadeiro depois que o mundo que ele descreveu mudou.

Um jardim é a metáfora honesta. Você não escreve um jardim uma vez. Você também não o audita trimestralmente, ou ele é um campo de ervas daninhas até a primavera. Você o cuida continuamente: você nota a coisa que está crescendo demais sobre o caminho, você arranca a erva enquanto está pequena, você pega a deriva antes que vire uma bagunça. O trabalho é constante, de baixo risco, e exatamente o tipo de atenção que humanos esgotam primeiro, que é por que jardins deixados às boas intenções morrem.

Isso é documentação. Não um problema de escrita, um problema de cuidado. O doc não ficou errado porque alguém esqueceu. Ele ficou errado porque nada estava observando o diff. Um jardineiro é só um observador com um propósito: ele vê o que a última mudança perturbou, e arranca a erva, a frase agora-falsa, antes que alguém confie nela. O corpus permanece vivo não porque alguém o reescreveu, mas porque algo nunca parou de cuidá-lo.

E uma vez que você tem um observador lendo cada diff contra o corpus inteiro, jardinagem é a metade menor do que ele consegue fazer. O mesmo agent que nota que um doc ficou desatualizado pode notar que um doc nunca foi escrito, o novo endpoint que ninguém documentou, a chave de config que apareceu sem explicação, o passo do runbook que existe no código e em lugar nenhum na prosa. A deriva que ele pega não é só “o doc diz algo falso”. É também “o código diz algo que os docs nunca mencionaram”. Ambos são intervalos entre o que é verdade e o que está escrito. O observador fecha ambos, do mesmo jeito, falando no momento em que o intervalo se abre.

A virada: quem paga por um doc desatualizado, e quem para de ter que pagar

Recue do mecanismo e olhe para quem de fato carrega o custo da deterioração da documentação, porque nunca é a pessoa que a causou.

O engenheiro que renomeou a função seguiu em frente, correto em seu próprio contexto, nunca errado por um segundo. O custo aterrissou rio abaixo, dias ou semanas depois, em alguém com menos contexto e sem aviso: o novo contratado no terceiro dia, o engenheiro de plantão às 3 da manhã, o colega que confiou no doc da API e perdeu uma tarde por uma promessa que o código não mantinha mais. Docs desatualizados são um imposto com a incidência mais cruel possível, a pessoa que menos pode arcar com a confusão paga por uma mudança que nunca viu.

Um observador que lê cada diff não torna a documentação sem esforço. Ele a torna atual, que é a única propriedade que sempre importou. Um doc atual é um colega que te diz a verdade. Um doc desatualizado é um colega que te diz com confiança algo que deixou de ser verdade na terça passada, e você não consegue distinguir até já ter confiado nele. O valor inteiro de escrever algo é que a próxima pessoa possa confiar nisso. No momento em que pode estar mentindo, esse valor se foi, e um doc em que ninguém pode confiar é pior que nenhum doc, porque ao menos nenhum doc não finge.

Então a pergunta não é se um agent consegue escrever sua documentação. É se algo está observando o intervalo entre o que seu código faz e o que você escreveu que ele faz, e se isso fala no momento em que o intervalo se abre, enquanto o conserto ainda é uma linha barata, em vez de meses depois, na frente da pessoa menos equipada para pegar a mentira.

---

É isso que estamos construindo na Apollo: não um editor de docs mais esperto, mas um observador que lê cada mudança contra tudo o que você escreveu e arranca a erva antes que alguém confie nela. Se você já seguiu um guia de setup direto para uma parede, você já sabe que o doc não foi preguiçoso. Ele só estava sem observação.