Não sei se foi os ramos que trabalhei (primeiro a área de turismo e hotelaria, agora atuo com softwares comerciais e emissores fiscais, contábeis e trabalhistas), mais sempre a documentação é feita ANTES da execução física.
Ou seja, primeiro, é feito toda a etapa de projeto, impactos no software e nas rotinas de trabalho, esse trabalho é feito pelo engenheiro de software, no segmento fiscal e trabalhista a grande parte do trabalho vem de exigências, leis e normativas que tem que obrigatoriamente serem seguidas, então, não tem muito como fugir, a documentação vem e temos o prazo para a adaptação do software.
Já nas demais, é mais permissivo, e a diretoria, gestão de produto e gestão técnica se alinham, no que será feito, é feito o planejamento e cronograma e segue o trabalho. Porém, sempre as fases iniciais são o projeto, analise de risco, impacto, documentação e execução.
Ou seja, durante o projeto, já fazemos as devidas atualizações da documentação técnica e operacional, nunca uma tabela ou estrutura seria criado ou atualizado sem que a documentação tenha sido APROVADA ANTES, ou seja, a fonte da verdade é SEMPRE o projeto técnico.
Não existe falta de tempo, pois dentro do cronograma já existe o numero de horas do ou dos profissionais que vão trabalhar as documentações do usuário, dos times de desenvolvimento e a documentação técnica da equipe de projeto.
No meu caso, algumas regras fiscais acabam mesmo entrando DEPOIS, sendo implementadas primeiro e um bom controle dessas sprints tem que ser feito, e extremamente documentado. Perder o controle ou deixar de atualizar não é nem de longe uma alternativa.
No segmento de turismo, a documentação existia, e era sempre atualizada, mesmo com um rigor menor, sempre o time de engenharia era o responsável pela sua atualização, e na pior situação a sprint era entregue JUNTO com a atualização, ou seja, a atualização de documentação é parte do trabalho, e a tarefa só é concluída se todas as suas partes também são.
Esperava ver outros relatos, mais acredito que a grande maioria segue essa regra.... a não ser empresas menores que acabam tendo maiores sobrecargas e deixam de lado pontos importantes para priorizar a maquiagem, a grande maioria das que trabalhei nos últimos 25a mantem tudo muito bem documentado. Algumas que não tinham isso mais cedo ou mais tarde descobriram que é um investimento, e que poupa tempo de trabalho e custos financeiros.
Concordo contigo que, em ambientes mais regulados (fiscal, contábil, trabalhista), a documentação precisa vir antes e ser aprovada, porque a própria natureza do negócio não permite improviso. Nesses cenários, o projeto técnico realmente é a fonte da verdade.
O ponto que tenho observado com mais frequência é fora desses ambientes: produtos digitais, SaaS, startups e até times médios, onde a pressão por entrega contínua e mudança rápida acaba quebrando esse modelo ideal. Não por discordância conceitual. quase todo mundo concorda que documentar é essencial — mas porque, na prática, a manutenção manual não escala bem quando as mudanças são constantes.
Por isso vejo cada vez mais valor em reduzir ao máximo a dependência exclusiva do fator humano. Quando diagramas e documentação conseguem ser derivados automaticamente daquilo que foi implementado, ou pelo menos sincronizados com a execução real, o risco de divergência cai muito. A documentação continua sendo parte do trabalho, mas deixa de ser um gargalo ou um ponto frágil do processo.
No fim, acho que estamos falando do mesmo objetivo: evitar dívida técnica e perda de controle. A diferença é o caminho. Em contextos ideais e bem estruturados, o projeto continua sendo a fonte da verdade. Em contextos mais dinâmicos, a automação vira uma aliada para garantir que essa verdade não se perca ao longo do tempo.
existem diversas ferramentas de WorkBench para "gerar" o código, a estratégia de CI/CD a partir de mudanças no Diagrama, se estiver-mos usando as ferramentas corretas de modo correto, uma atualização de diagrama já "cospe" o pipeline que será necessário no CI/CD e o novo diagrama, mostra para os Devs o que fazer, e como fazer.
Startups hoje, em suma maioria, usam a estratégia de fatiar pão francês com motosserras, ou seja, partem para uma solução que aparenta ser viável e escalável, e barata. No caso, quando tiverem milhares de usuários a faca terá que ser mecanizada e automática para fatiar muito mais pães sem precisar de pessoas, porém uma maquina industrial de fatiar pães custa muito caro, e uma motosserra que consegue cortar arvores também deve servir.
SaaS existem alguns muito bons, hoje virou roupa, todo mundo tem e quer usar da maneira que se sente melhor, alguns tem qualidade, outros tem preço, outros tem disponibilidade.... na pior situação dessas 3 opções você fica com 2.
Infelizmente, o modelo de negócios de alguns projetos acaba priorizando a divida técnica. A filosofia ágil foi distorcida para se tornar sinônimo de sem documentação ou que a entrega é a prioridade, o resto fica pra depois.
O ágil, realmente, é ter o controle de cada pequena ação cada pequeno sprint, e ser tão SIMPLES que no final do SPRINT ele já esta AUTODOCUMENTADO a filosofia, deveria seguir o principio de que ao colocar a mão na massa e fazer, o projeto já foi definido ANTES. Ou seja, é o ponto CENTRAL não o gargalo.
Em times menores, esse cenário deveria ser ainda mais importante, tudo o que foi planejado antes deveria estar em execução, a dinamicidade, vem mascarando a falta de conhecimento, ou a vontade de empurrar com a barriga disfarçado de velocidade.
Desculpe, bato muito nesse contexto, pois a cada dia, o mercado DEV vem perdendo qualidade, o ego de muitos gerentes de projeto, acaba destruindo o mercado. Quando mudamos a prioridade, mais cedo ou mais tarde, temos a cobrança da dívida.
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.