Boas práticas de documentação da Modelagem de Dados: dicionário, glossário e rastreabilidade

O que é “documentação útil e auditável” na Modelagem de Dados

Documentação útil é a que permite que diferentes pessoas (negócio, TI, auditoria, dados) entendam o mesmo significado e cheguem às mesmas decisões ao ler o modelo. Documentação auditável é a que deixa rastros: quem decidiu, quando, por quê, com base em quais requisitos e quais impactos foram aceitos (trade-offs).

Na prática, isso se materializa em um conjunto mínimo de artefatos conectados entre si: glossário de termos do negócio, dicionário de dados (tabela/coluna), catálogo de regras de negócio, matriz de rastreabilidade (requisito → entidade/atributo/regra) e convenções de nomenclatura. A qualidade vem de critérios explícitos: completude, consistência e ausência de ambiguidades.

Glossário de termos do negócio (linguagem comum)

Conceito

O glossário define o significado de termos do domínio (ex.: “Cliente”, “Pedido”, “Cancelamento”, “Ativo”, “Elegível”) em linguagem de negócio, com sinônimos, termos proibidos e exemplos. Ele reduz ambiguidades e evita que o dicionário de dados vire um conjunto de nomes técnicos sem semântica.

Boas práticas

• Uma definição por termo, curta e verificável (evite definições circulares: “Cliente é quem é cliente”).
• Inclua contraexemplos quando houver confusão comum (o que não é o termo).
• Registre sinônimos e termos preferidos (ex.: “CPF” preferido; “Cadastro de Pessoa Física” como sinônimo).
• Indique o contexto quando o termo muda de significado por área (ex.: “Ativo” em Financeiro vs. “Ativo” em RH).
• Versione e registre o responsável (owner) do termo.

Modelo de registro (template)

Passo a passo prático

1. Extraia termos candidatos de requisitos, telas, relatórios e conversas (substantivos e expressões recorrentes).
2. Agrupe sinônimos e escolha o termo preferido (um nome oficial).
3. Escreva definições testáveis: alguém consegue dizer “sim/não” se um caso se enquadra?
4. Valide com o negócio em revisão rápida (30–60 min) focada em ambiguidades.
5. Congele uma versão para o ciclo de entrega e registre mudanças futuras via histórico.

Dicionário de dados (tabela/coluna) como contrato

Conceito

O dicionário de dados descreve cada objeto persistido (tabelas/visões) e cada atributo (coluna) com significado, formato, regras de preenchimento e exemplos. Ele é o “contrato” entre quem produz e quem consome dados.

O que documentar por tabela

• Descrição (o que representa no negócio).
• Owner (área responsável pelo significado).
• Granularidade (o que é “uma linha” da tabela).
• Fonte (sistema/origem) e frequência de atualização (se aplicável).
• Chaves e relacionamentos relevantes (referências principais).
• Regras associadas (IDs de regras no catálogo).

O que documentar por coluna

• Nome lógico (negócio) e nome físico (implementação), quando diferentes.
• Definição (semântica).
• Tipo e formato (ex.: DECIMAL(10,2), máscara, unidade).
• Obrigatoriedade (pode ser nulo?) e valor padrão (se existir).
• Domínio (lista de valores, faixa, referência a tabela de domínio).
• Regras de derivação (se calculado) e origem (se vindo de outro sistema).
• Exemplos válidos e exemplos inválidos.
• Classificação (sensibilidade/privacidade) quando aplicável.

Modelo de dicionário (template)

Passo a passo prático

1. Liste as tabelas/entidades que serão entregues e defina a granularidade de cada uma (uma frase: “uma linha representa…”).
2. Para cada coluna, escreva a definição em linguagem simples e adicione 1–2 exemplos válidos.
3. Amarre domínios e regras usando IDs do catálogo de regras (evite repetir texto de regra em múltiplos lugares).
4. Revise consistência de nomes com as convenções (seção de nomenclatura).
5. Faça uma revisão cruzada com o glossário: termos do dicionário devem referenciar termos do glossário quando forem conceitos de negócio.

Catálogo de regras de negócio (regras como itens rastreáveis)

Conceito

O catálogo de regras é uma lista numerada e versionada de regras, cada uma com descrição, motivação, escopo, exceções e forma de validação. Ele evita que regras fiquem “espalhadas” em e-mails, comentários e reuniões.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Campos recomendados

• ID (ex.: RB-012) e título.
• Descrição normativa (use “deve/não deve”).
• Justificativa (por que existe).
• Escopo (onde se aplica) e exceções.
• Impacto no modelo (entidades/atributos afetados).
• Tipo (validação, cálculo, temporal, integridade, privacidade etc.).
• Como testar (critério verificável) e exemplos.
• Status (proposta, aprovada, implementada, depreciada) e responsável.

Modelo (template)

Matriz de rastreabilidade (requisito → entidade/atributo/regra)

Conceito

A matriz de rastreabilidade conecta requisitos (funcionais, relatórios, integrações, compliance) aos elementos do modelo e às regras. Ela permite responder perguntas de auditoria e de impacto: “onde este requisito está atendido?”, “se eu mudar este atributo, quais requisitos quebram?”

Estrutura recomendada

Passo a passo prático

1. Numere requisitos (REQ-001, REQ-002…) e mantenha a descrição curta.
2. Para cada requisito, identifique quais tabelas/colunas o atendem.
3. Associe regras por ID (RB-xxx) quando o requisito implicar validação/cálculo/condição.
4. Marque lacunas: requisito sem mapeamento indica item não atendido; elemento do modelo sem requisito pode indicar “escopo extra” (confirmar).
5. Use a matriz em revisões de mudança: toda alteração deve atualizar as linhas afetadas.

Convenções de nomenclatura (consistência e legibilidade)

Conceito

Convenções definem padrões para nomes físicos e lógicos (tabelas, colunas, chaves, constraints, índices), reduzindo ruído e facilitando manutenção. O objetivo é previsibilidade: ao ver um nome, a pessoa infere o tipo de dado e o papel no modelo.

Regras práticas (exemplos)

• Tabelas: substantivo no singular, sem abreviações ambíguas (ex.: pedido, cliente).
• Colunas: snake_case, prefixos semânticos quando ajudam (ex.: dt_criacao, vl_total apenas se a equipe adotar e documentar).
• Chaves primárias: id (quando padrão por tabela) ou id_pedido (quando preferir explícito).
• Chaves estrangeiras: id_cliente apontando para cliente.
• Booleans: prefixo fl_ ou is_/tem_ (um padrão só) e valores consistentes.
• Datas: diferenciar data vs. data-hora no nome (ex.: dt_pagamento vs. dh_pagamento).
• Constraints: padrão como pk_tabela, fk_tabela_coluna, ck_tabela_regra, uq_tabela_coluna.

Checklist de convenções

• Nomes sem acentos e sem espaços.
• Evitar siglas não padronizadas; manter lista de siglas permitidas.
• Evitar nomes genéricos (codigo, descricao) sem qualificador (codigo_produto, descricao_status).
• Padronizar idioma (todo o esquema em PT ou todo em EN).

Registro de decisões e trade-offs (log de arquitetura do modelo)

Conceito

Decisões de modelagem frequentemente envolvem trade-offs (simplicidade vs. flexibilidade, performance vs. normalização, compatibilidade com legado vs. pureza conceitual). Registrar decisões evita retrabalho e “rediscussões infinitas”, além de apoiar auditorias e onboarding.

Quando registrar uma decisão

• Quando houver alternativas reais e uma escolha impactar o futuro.
• Quando a decisão for irreversível ou cara de mudar (ex.: padrão de chaves, estratégia de histórico, codificação de status).
• Quando houver exceções às convenções.
• Quando a decisão for motivada por restrição externa (legado, integração, compliance).

Modelo de registro (ADR simplificado)

Passo a passo prático

1. Crie um repositório de decisões com IDs sequenciais (DEC-001…).
2. Para cada decisão, escreva contexto e alternativas antes da reunião de validação.
3. Registre a decisão final e os trade-offs aceitos (inclusive riscos).
4. Vincule a requisitos (REQ), regras (RB) e elementos do dicionário (tabela/coluna).
5. Atualize o status se a decisão for substituída (não apague; marque como revogada e referencie a nova).

Critérios de qualidade da documentação

Completude

• Todo termo crítico do negócio está no glossário.
• Toda tabela e coluna do escopo está no dicionário com definição e exemplo.
• Toda regra relevante tem ID, status e forma de teste.
• Todo requisito tem ao menos um mapeamento na matriz (ou está explicitamente “fora de escopo”).

Consistência

• O mesmo conceito tem o mesmo nome (termo preferido) em glossário, dicionário e regras.
• Domínios e unidades são coerentes (ex.: moeda sempre BRL; datas sempre UTC/local conforme padrão).
• IDs referenciados existem (REQ-xxx, RB-xxx, DEC-xxx) e não há duplicidade.

Ausência de ambiguidades

• Definições evitam palavras vagas (“apropriado”, “normal”, “regular”) sem critério.
• Campos como “status” especificam valores permitidos e significado de cada valor.
• Regras têm exceções explicitadas (ou afirmam “nenhuma”).

Auditabilidade

• Owner e versão em glossário, regras e decisões.
• Histórico de mudanças (o que mudou e por quê).
• Rastreabilidade bidirecional: requisito → modelo e modelo → requisito.

Pacote mínimo recomendável (MVP) e como manter vivo

Pacote mínimo

• Glossário com termos críticos e sinônimos.
• Dicionário de dados com todas as tabelas/colunas do escopo.
• Catálogo de regras com IDs e testes.
• Matriz de rastreabilidade cobrindo requisitos priorizados.
• Convenções de nomenclatura em 1–2 páginas.
• Log de decisões para escolhas estruturais.

Rotina de manutenção (prática)

1. Defina “pronto” (Definition of Done): mudança no modelo só é aceita com atualização do dicionário + rastreabilidade + regra/decisão quando aplicável.
2. Revisões rápidas: a cada alteração relevante, revisar 5 itens: nome, definição, domínio, regra associada, requisito associado.
3. Controle de versão: cada entrega do modelo referencia versões do glossário/dicionário/regras/decisões.
4. Auditoria interna: amostrar 10% das colunas e verificar se definição, exemplo e regra estão presentes e coerentes.