Documentação técnica com IA: como escrever a que alguém realmente lê

Documentação sempre foi a tarefa que todo mundo concorda ser importante e ninguém quer fazer. Com IA, escrever ficou trivial — e apareceu um problema novo, que eu não previa: times com muita documentação e nenhuma resposta.

Páginas e páginas descrevendo o que o código já diz, tudo bem escrito, tudo inútil. Porque documentação não tem valor por existir. Tem valor por responder a pergunta que alguém fez às onze da noite tentando entender por que aquilo está daquele jeito.

A distinção que resolve quase tudo: o quê versus o porquê

Toda documentação técnica cai em uma de duas categorias:

• O quê / como: o que essa função faz, quais parâmetros aceita, como rodar o projeto, qual endpoint retorna o quê.
• O porquê: por que escolhemos este banco, por que essa função tem esse tratamento estranho, por que não usamos a biblioteca óbvia, o que já tentamos e falhou.

A primeira categoria é derivável do código — e é justamente onde a IA é excelente, porque a fonte da verdade está ali. A segunda só existe na cabeça de quem decidiu. Se ninguém escrever, some quando a pessoa sai.

A IA escreve muito bem a documentação que o código já contava. A que importa é a que só você sabe — e essa ninguém pode escrever no seu lugar.

O erro dos times que adotaram IA sem critério foi multiplicar a primeira categoria e continuar não escrevendo a segunda. O resultado é um volume que dá impressão de organização e não responde a nenhuma pergunta real.

O que delegar sem culpa

• Referência de API a partir do código: parâmetros, tipos, retorno, erros possíveis. Trabalho mecânico e verificável.
• Descrição de componente: props, variantes, estados, exemplo de uso.
• Passo a passo de instalação derivado dos arquivos de configuração reais.
• Resumo de módulo legado: "leia estes arquivos e explique o que esse módulo faz e como as peças se conectam". Um dos usos de maior retorno que existem.
• Changelog a partir do histórico de commits.
• Glossário dos termos de domínio que aparecem no código — ótimo para quem entra no time.
• Tradução e revisão do que você escreveu correndo.

O que escrever à mão, sempre

• Decisão de arquitetura e a alternativa descartada. Principalmente o que você tentou e não funcionou — é a informação mais cara de reconstruir e a que mais evita repetição de erro.
• O aviso. "Não mexa nessa ordem de chamada, quebra a integração com o parceiro X." Isso não está no código e é o que evita incidente.
• Contexto de negócio. Por que a regra é essa, quem pediu, o que acontece se mudar.
• O mapa de entrada: por onde alguém novo começa a ler. Exige julgamento sobre o que importa — e julgamento é a única coisa que não dá para delegar.

Três armadilhas específicas

1. Documentação que descreve o código linha a linha

Peça um README e você provavelmente recebe uma narração do que já está visível: "a função calcularTotal calcula o total". Isso não é documentação, é redundância — e redundância envelhece: o código muda, o texto fica, e agora você tem informação errada com aparência de oficial.

Correção no pedido: "não descreva o que o código já mostra. Documente apenas o que não é óbvio pela leitura: premissas, efeitos colaterais, casos-limite e o motivo das escolhas estranhas."

2. O confiante que inventa

Ao documentar código que não recebeu, a IA preenche lacuna com o que seria razoável. Você recebe uma seção de configuração descrevendo variáveis de ambiente que não existem, ou um endpoint com parâmetro imaginado.

Isso é pior que não ter documentação: gera confiança falsa e faz alguém perder uma hora tentando usar algo inexistente. Peça sempre: "se não estiver no código que forneci, escreva [VERIFICAR] em vez de supor." E confira toda seção de configuração à mão — é onde ela mais inventa.

3. Volume como métrica

Como ficou barato produzir, a tentação é documentar tudo. Mas documentação tem custo de manutenção proporcional ao volume: cada página é uma coisa a mais que pode ficar desatualizada e enganar alguém.

Regra que uso: documento só o que responde a uma pergunta que alguém já fez. Perguntaram duas vezes no chat? Vira documentação. Nunca perguntaram? Provavelmente não precisa existir.

O fluxo que funciona

1. Você escreve o esqueleto — os títulos, na ordem que faz sentido para quem vai ler. Cinco minutos, e é aqui que mora o julgamento.
2. Você escreve à mão as seções de "porquê", em texto corrido e feio se precisar. Conteúdo, não forma.
3. A IA preenche as seções descritivas a partir do código real, com a instrução de marcar o que não puder verificar.
4. A IA revisa o conjunto no papel de quem vai ler: "você é alguém que entra no time amanhã. O que ainda não dá para entender aqui?"
5. Você confere comando, caminho de arquivo e nome de variável. É onde estão os erros.

Como saber se a documentação está viva

Duas verificações simples, de tempos em tempos:

• O passo a passo de instalação funciona numa máquina limpa? É o teste mais brutal e o mais honesto. Se falha no passo 3, todo o resto é decorativo.
• Quando alguém perguntou algo no chat, a resposta estava documentada? Se estava e a pessoa não achou, o problema é de organização, não de conteúdo. Se não estava, você acabou de descobrir o que escrever.

O resumo

A IA transformou documentação de "trabalho que ninguém faz" em "trabalho que qualquer um faz rápido demais". O gargalo mudou de lugar: não é mais escrever, é decidir o que merece existir e garantir que seja verdade.

Delegue o descritivo, escreva à mão o porquê, proíba a suposição e documente só o que responde pergunta real. Um documento curto e correto vale mais que um portal inteiro que ninguém confia — porque documentação em que não se confia, não se lê.