Como documentar um sistema legado sem documentação
Você herdou um sistema que funciona, mas ninguém sabe como. O desenvolvedor original sumiu, não existe documentação, e qualquer alteração é um risco.
Antes de pensar em trocar, documente. Aqui está como.
Por que documentar antes de decidir
- Você entende o que o sistema realmente faz
- Consegue estimar o esforço de migração
- Pode fazer manutenções emergenciais
- Reduz dependência de adivinhação
Passo 1: Mapeie as funcionalidades
Comece pelo que o sistema faz, não por como faz.
Liste todas as funcionalidades que os usuários utilizam:
- Cadastro de clientes
- Emissão de pedidos
- Relatório de vendas
- ...
Pergunte para quem usa no dia a dia. Eles sabem o que o sistema faz, mesmo sem entender o código.
Passo 2: Mapeie os fluxos principais
Para cada funcionalidade importante, documente o fluxo:
- Usuário clica em "Novo Pedido"
- Preenche cliente e produtos
- Sistema calcula total
- Usuário confirma
- Sistema grava no banco e gera número
Não precisa ser técnico ainda. Foque no processo.
Passo 3: Identifique a estrutura do banco
O banco de dados é a "verdade" do sistema. Analise:
- Quais tabelas existem?
- Quais campos cada tabela tem?
- Como as tabelas se relacionam?
Ferramentas como DBeaver ou o próprio SQL Server Management Studio ajudam a visualizar.
Passo 4: Rastreie o código dos fluxos críticos
Agora sim, vá para o código. Mas com foco:
- Escolha um fluxo crítico (ex: fechar pedido)
- Encontre o ponto de entrada (botão, tela, endpoint)
- Siga o código passo a passo
- Anote o que cada parte faz
Use a técnica de "rubber duck debugging": explique o código em voz alta como se estivesse ensinando alguém.
Passo 5: Documente integrações
O sistema conversa com outros? Documente:
- Com quem integra?
- Como? (API, arquivo, banco direto)
- Qual a frequência?
- O que é transmitido?
Passo 6: Registre as regras de negócio
O mais valioso e mais difícil: as regras escondidas no código.
- Por que esse desconto é aplicado?
- Por que esse campo é obrigatório só às vezes?
- O que acontece quando o estoque fica negativo?
Essas regras geralmente estão enterradas em IFs e funções. Documente cada uma que encontrar.
Ferramentas úteis
- Draw.io: Diagramas de fluxo
- Notion/Confluence: Documentação centralizada
- DBeaver: Análise de banco de dados
- Git blame: Ver quem alterou o quê (se tiver controle de versão)
Formato sugerido de documentação
- Visão geral: O que o sistema faz, tecnologias usadas
- Funcionalidades: Lista do que existe
- Fluxos principais: Como os processos críticos funcionam
- Estrutura de dados: Tabelas e relacionamentos
- Integrações: Sistemas conectados
- Regras de negócio: Lógicas importantes
- Problemas conhecidos: Bugs, limitações, gambiarras
Conclusão
Documentar sistema legado dá trabalho, mas é investimento. Com documentação, você pode manter, migrar ou substituir com segurança. Sem ela, qualquer decisão é no escuro.
Serviço relacionado: a Cierus resolve isso na prática — veja Sistema Legado.