Documentação como produto: quem não tem dono, não tem leitor

Existe um padrão que se repete em quase todo time de tecnologia: a documentação é a última prioridade do trimestre e a primeira reclamação do suporte. Todo mundo concorda que ela importa; ninguém tem tempo. O resultado é uma pasta de documentos que descreve um sistema que não existe mais.

A causa quase nunca é preguiça. É ausência de dono, de usuário definido e de critério de sucesso. Em outras palavras: a documentação não é tratada como produto — é tratada como sobra.

Quem é o usuário da documentação

A primeira pergunta de qualquer produto é "para quem". Na documentação, ela raramente é feita, e por isso o texto tenta agradar todo mundo:

• Quem lê para decidir se adota a ferramenta (5 minutos, quer escopo e limite).
• Quem lê para fazer a primeira coisa funcionar (30 minutos, quer tutorial linear).
• Quem lê para resolver um caso específico (quer referência e busca).
• Quem lê para entender por que a decisão foi tomada (quer registro histórico).

São quatro documentos diferentes. Tentar escrever um só produz o híbrido que conhecemos: uma introdução longa, exemplos que não rodam e nenhuma explicação de trade-off.

Três decisões que mudam a qualidade

1. Escolher um usuário principal. Se você só pode manter uma coisa, mantenha o caminho de primeira execução: da instalação ao primeiro resultado visível, testado em máquina limpa. Isso resolve a maior parte do suporte.

2. Dar dono nominal, com tempo reservado. Não "o time". Uma pessoa. E tempo no ciclo, não no fim do projeto. Documentação escrita depois do prazo é ficção.

3. Tratar o exemplo como teste. Todo trecho de código na documentação deveria rodar na CI. Se quebra o build, quebra a documentação — e alguém conserta.

Documentação ruim não é um problema de escrita. É um problema de prioridade: o documento não tem usuário, não tem dono e não tem verificação. Troque esses três e o texto melhora sozinho.

A métrica que importa

Equipes medem documentação por volume — número de páginas, cobertura de endpoints. É a métrica errada, pelo mesmo motivo que linhas de código é métrica errada.

A que serve é tempo até o primeiro sucesso: quanto tempo uma pessoa de fora leva, sem ajuda humana, para sair de zero e chegar a um resultado útil. Cinco pessoas diferentes tentando, cronômetro na mão, e você tem um número honesto.

Se esse número cai a cada trimestre, a documentação está funcionando. Se não cai, você tem mais páginas — e o mesmo produto inexplicável.

O efeito colateral bom

Time que documenta bem escreve melhor código. Não por mágica: escrever o uso revela o que a interface faz de confuso, e a decisão de design ruim aparece antes de virar dívida. Documentação, feita no lugar certo do ciclo, é revisão de design disfarçada.