Excesso de documentação

Documentar uma decisão custa manter uma decisão

A documentação ajuda quando alguém consegue decidir ou executar algo com ela. Um arquivo que repete outro sem declarar qual prevalece aumenta o trabalho: cada mudança exige conferir duas versões e cada divergência transfere ao leitor a escolha da verdade. Orçamento documental é a decisão explícita sobre quais registros merecem ser produzidos e mantidos. Não é uma quota universal de páginas nem uma autorização para apagar evidências incômodas.

Na Oficina Caracol, o catálogo público, os testes e a operação de reserva simulada possuem responsabilidades distintas. O README conduz a execução; o registro de decisão explica uma escolha durável; a evidência identifica uma verificação; o gate decide se os resultados permitem avançar. Escrever quatro descrições diferentes do comando de teste não melhora nenhum desses papéis. Uma descrição canônica e três remissões são mais fáceis de corrigir.

Caso trabalhado de consolidação

Considere este caso didático: a equipe criou doze arquivos ao planejar o catálogo. Quatro repetem requisitos, três ensinam a iniciar o servidor, dois contêm decisões contraditórias e três guardam resultados de ensaios de versões diferentes. A contagem identifica trabalho de revisão, mas não determina o que descartar. A decisão é preservar a informação necessária e retirar a competição entre autoridades.

A tabela é o orçamento decidido para esse conjunto de informações, não uma proibição de novos documentos. Os resultados antigos permanecem identificados como históricos. Os arquivos repetidos deixam de ser fontes vigentes e passam a remeter ao registro escolhido, conforme a política de histórico do projeto. Uma decisão que perdeu validade recebe uma decisão sucessora; sua justificativa não desaparece silenciosamente.

Procedimento de revisão

• Identifique o leitor e uma ação concreta que cada documento precisa permitir. Se não houver ambos, investigue seu valor antes de mantê-lo por hábito.
• Agrupe afirmações repetidas e escolha a autoridade de cada domínio: requisitos, execução, decisões e resultados não precisam morar no mesmo arquivo.
• Compare divergências com o comportamento e as decisões autorizadas. Não escolha o documento mais recente apenas pela data.
• Consolide o conteúdo vigente, preserve o histórico necessário e acrescente remissões. Registre quem mantém cada autoridade.
• Peça a outra pessoa que encontre o comando de teste e a última decisão aplicável sem recorrer ao autor. Registre dificuldade e corrija a navegação.

Erros e reparos específicos

• Apagar todos os registros antigos reduz volume e pode destruir a explicação de uma mudança. Reparo: distinguir documento vigente, histórico preservado e duplicação dispensável antes de excluir.
• Criar um relatório para cada conversa dispersa decisões. Reparo: resumir apenas o que muda um compromisso, um risco ou o próximo passo, na autoridade correspondente.
• Centralizar tudo num arquivo gigantesco também cobra manutenção. Reparo: separar por pergunta e responsabilidade, mantendo uma entrada que permita localizar as partes.

Condição observável de avanço

A revisão pode avançar quando cada afirmação operacional relevante possui uma autoridade identificada, os vínculos chegam ao conteúdo vigente e o ensaio de localização encontra comandos e decisões sem contradição impeditiva. Uma quantidade pequena de arquivos, sozinha, não satisfaz esse gate. A pessoa responsável aceita explicitamente eventuais remissões quebradas que não afetem a execução, com prazo para correção.

Exercício com solução

Dados: A.md manda executar npm test; B.md manda executar npm run testes; C.md contém uma decisão de escopo ainda válida. O package.json disponível define test e não define testes. Proponha a consolidação sem perder a decisão.