Qualquer pessoa que já participou de um projeto de pelo menos um ano já se deparou com a seguinte situação: uma mensagem (email, sinal de fumaça, pombo correio) chega pra você dizendo que a funcionalidade X deveria funcionar desse jeito e não daquele jeito. Quase como se você tivesse escrito a mensagem, se dá conta de que faz todo sentido. Realmente a aplicação deveria funcionar dessa maneira. Mas por que não funciona assim?
Como tudo é urgente, você faz a alteração e devolve a mensagem dizendo que tudo está corrigido e teremos um final feliz. Após algum tempo, erros acontecem, inconsistências aparecem e tudo vai abaixo. Depois de horas de debug e alguns fios de cabelo a menos, você se dá conta que não é possível o sistema funcionar da maneira que foi pedida por alguns motivos bastante específicos e a alteração precisa ser revertida.
O que aconteceu? Por que ninguém te avisou sobre essa limitação? Esse é o propósito da documentação. Assim como livros são uma maneira de estender seu conhecimento a outras pessoas (ou você mesmo no futuro), a documentação compartilha a sua experiência e de outras pessoas com quem vem depois.
Entender os motivos e variáveis de quando uma decisão foi tomada é importantíssimo para que situações como a nossa historinha não aconteçam. Documentar é uma forma de ser eficiente e evitar retrabalhos.
É importante ressaltar que não me refiro a documentação de usuário, nem a comentários de código ou exemplos de uso de APIs. Esse tipo de documentação, apesar de muito importante, tem propósitos bastante distintos.
Utilizar técnicas como ADRs (architectural decision recorda), Postmortems, release notes e até mesmo controles de versão, são maneiras de comunicar o objetivo do código e de suas mudanças.
ADRs, por exemplo, servem para comunicar decisões de arquitetura e domínio, como escolhas de stack, estratégias de integração e uso de bibliotecas e frameworks.
Já postmortems (prefiro AAR ou After Action Reports) servem para relatar intervenções necessárias. Problemas em produção, deploys mal sucedidos, funcionalidades canceladas e falhas completas. É importante analisar não só o problema mas também os motivos de ter acontecido. Gosto também de incluir ações preventivas, com foco em evitar que a situação volte a acontecer.
Por fim, pode ser chato e doloroso documentar, mas garanto que vai ser ainda pior no futuro, quando precisar e não tiver. E acredite em mim, você VAI precisar.