Acho que a gente concorda em mais pontos do que parece — principalmente no objetivo final: controle, previsibilidade e redução de dívida técnica.
Onde vejo a divergência não é no valor da documentação nem no modelo ideal, mas na aderência desse modelo ao contexto mais comum hoje, especialmente fora de ambientes altamente regulados.
Em setores como fiscal, contábil e trabalhista, o projeto técnico precisa ser a fonte da verdade. Aí não existe espaço para improviso. Já em produtos digitais, SaaS e startups, o que observo com mais frequência é um cenário onde:
o domínio muda rápido
hipóteses são testadas em produção
decisões de schema acontecem em ciclos curtos
nem sempre há um “engenheiro de software” dedicado apenas ao projeto e documentação
Nesse contexto, o problema não é falta de consciência — é escala. Manter diagramas e documentação manualmente sincronizados com dezenas de migrations semanais simplesmente não se sustenta bem.
Por isso minha provocação não é “documentar menos”, e sim reduzir o quanto a documentação depende exclusivamente de disciplina humana. Quando o diagrama passa a ser:
derivado do schema real
versionado junto com migrations
integrado ao pipeline
tratado como artefato vivo do código
ele deixa de competir com a entrega e passa a fazer parte dela.
No fim, vejo dois caminhos convergindo para o mesmo ponto:
em ambientes maduros e regulados, o projeto segue sendo a fonte da verdade
em ambientes altamente dinâmicos, a automação ajuda a preservar essa verdade ao longo do tempo
Talvez o erro do mercado não seja abandonar o projeto, mas insistir em modelos manuais onde a realidade já exige algo mais integrado e automático.