Resposta direta
Contratar integração sem documentação começa por separar o que existe do que se sabe sobre ela. O histórico raramente está escrito; costuma estar no comportamento do sistema, nos registros de execução e nas pessoas que operaram o processo. Antes de contratar, um levantamento curto com evidência vale mais do que uma proposta detalhada: quais trocas de dados acontecem, com que frequência, o que ocorre quando falham e quem responde por cada ponta. Sem isso, o contrato compra risco mal medido. O escopo precisa dizer o que será documentado, o que será mantido e o que fica fora, incluindo o que não se consegue recuperar do passado.
- Objetivo
- Orientar avaliação e contratação
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Trata a ausência de documentação como item de escopo e de responsabilidade no contrato, não como detalhe técnico a resolver depois da assinatura.
O que a ausência de documentação encobre
Documentação ausente não significa comportamento desconhecido. Significa que o conhecimento está disperso em três lugares: no código que ninguém revisou, nos registros de execução e na memória de quem operou a rotina. Cada um cobre uma parte, e nenhum cobre o todo.
O risco de contratar sem levantar isso é comprar um escopo pelo que se imagina, não pelo que existe. Integrações antigas costumam acumular exceções criadas caso a caso, sem registro, que só aparecem no dia em que algo deixa de funcionar.
O que precisa estar no contrato antes da assinatura
O contrato precisa separar manutenção de reconstrução. Manter significa preservar o que existe e responder por falhas dentro de um escopo definido. Reconstruir significa reescrever a troca de dados a partir do comportamento atual. São escopos distintos, com esforço e risco distintos.
Também é preciso definir o que conta como entrega: mapa das trocas de dados, registro das regras conhecidas, procedimento de acionamento e responsável por cada ponta. Sem critério de aceite, a discussão sobre o que foi entregue fica sem referência.
O que a avaliação não resolve
Nenhum levantamento recupera o que nunca foi registrado. Regras que existiam apenas na cabeça de quem saiu da operação podem ter se perdido, e o comportamento atual pode ser resultado de correções que ninguém lembra ter feito.
Avaliar também não elimina o risco de falha durante a transição. O que a avaliação entrega é uma estimativa do tamanho do problema e um contrato que distribui responsabilidade. Ela não assegura que a nova versão se comportará igual à antiga.
Recurso prático
Lacuna de documentação e a evidência que a substitui
| O que não está documentado | Onde buscar evidência antes de contratar |
|---|---|
| Regras de transformação dos dados | Comparação de amostras de entrada e saída, com as diferenças registradas por escrito |
| Frequência e horário das execuções | Histórico de execuções e registros de erro do período ainda disponível |
| Quem responde quando a troca falha | Registro de acionamentos e chamados do último período em que houve falha |
| Limites de volume e tempo de resposta | Teste controlado com volume conhecido, com resultado anotado e datado |
O ponto mais ignorado é o comportamento em falha: quase toda proposta descreve o caminho normal e nenhuma descreve o que acontece quando a troca não completa. É aí que o custo de manutenção aparece depois da assinatura.
Conceitos usados nesta página
- Registro de execução — Registro de execução é a evidência de que uma rotina, automação ou tarefa rodou — com identificador, data, insumo, resultado e responsável.
- Critério de aceite — Critério de aceite é a condição objetiva que define quando uma entrega, tarefa ou automação é considerada concluída — verificável por quem recebe, não por quem produziu.
Sobre o que está escrito aqui
Conceitos relacionados: contrato de manutenção · registro de execução · mapa de troca de dados · critério de aceite · responsável por cada sistema. Exemplos são ilustrativos. Não há cliente, resultado, preço, prazo ou certificação nesta página. Quando o formato indicado é Projeto de implementação, ele descreve uma possibilidade de trabalho — a conversa inicial avalia contexto e aderência.
Para continuar
- Integrações, sistemas e qualidade de dados — Página central do tema
- Dados desatualizados: o que precisa estar em dia — dados desatualizados
- Validação na entrada: onde o dado errado nasce — dado errado na origem
Páginas relacionadas
O mesmo problema em outro objetivo
- Integração sem documentação: como reconstruir o que ela faz — Diagnosticar
- Integração sem documentação: como reconstruir o registro — Organizar um processo
- Integração sem documentação: o que comparar antes de mexer — Comparar alternativas
- Integração sem documentação: como medir o que ficou — Explicar medição
- Integração sem documentação: por onde reconstruir o contrato — Orientar implementação
Outras leituras em Integrações, sistemas e qualidade de dados
- Integração parou sem avisar: como achar quando e onde — Maneira de reconstruir o intervalo em que uma integração parou sem alerta, pelos registros de entrada, saída e horário de execução.
- Base de teste diferente da produção: o que padronizar — Define o que a base de teste precisa reproduzir da produção, quem responde por mantê-la e quando ela deixa de servir para validar.
- Migração que não anda: como separar dado, processo e decisão — Separa as causas que travam uma migração, entre dado, processo e responsabilidade, e indica o que medir antes de decidir o corte.
- Base de teste diferente da produção: o que exigir no contrato — O que pedir ao fornecedor sobre ambiente de homologação com dados parecidos com a produção, quem responde por isso e o que fica fora.
- Campo com formatos diferentes: o que exigir no contrato — O que acordar ao contratar tratamento para campo preenchido de formas diferentes: regra única, responsável definido e critério de aceite verificável.