“No princípio, Deus criou os céus e a terra” (Gênesis 1:1)

Já passou alguma vez por uma documentação que, ao invés de descrever o que o sistema faz, conta a história deste? Algo similar a “No princípio, Fulano criou o sistema para fazer isso” - praticamente uma versão em texto corrido daquela tabela de “histórico de alterações” (cuja origem desconheço).

Implementar um sistema baseando-se nesse tipo de documentação é como fazer manualmente um “merge”, revisão por revisão, de um arquivo no sistema de controle de versão.

Se o sistema originalmente considerava multa de 20% e, por definição do chefe do setor, passou a considerar multa de 10%, por que precisa documentar isso no modelo de análise? Só para ter o gosto de ouvir o programador perguntar: “devo sempre considerar 10% ou tem algum caso que ainda vale 20%”?

Muito mais claro, resumido e conciso seria documentar que o sistema “deve considerar multa de 10%”. Se a intenção é documentar a história, existem locais melhores para isso, como a tabela de histórico da capa, o histórico no sistema de versionamento ou uma ata de reunião.