Documentação para um projeto de BI

Documentar um projeto de BI vai muito além de criar tabelas... Precisamos entender a necessidade, mapear corretamente os dados, prever o crescimento futuro e garantir que qualquer profissional consiga dar manutenção no futuro com segurança.

Neste post vou mostrar passo a passo de como criei uma documentação e as ferramentas que utilizei. Dividi o projeto em quatro etapas, criei um sumário no Microsoft Word colocando o título dessas 4 etapas principais como Título 1 (principal) e os subtemas utilizei o Título 2 (secundário) e na medida em que fui desenvolvendo o projeto, fui preenchendo a documentação e no final, exportei para pdf e salvei como versão 01.

Um projeto bem documentado é sinônimo de transparência, controle e sucesso.

💻 Etapa 1: Detalhes do projeto

➡️ Nomes e áreas dos envolvidos

1. Quem são os demandantes do projeto?

2. Nome da área solicitante

3. Responsável técnico da área de negócios

4. P.O responsável

5. P.M.O responsável

6. Responsável B.I

➡️ Datas

1. Início do projeto

2. Conclusão Execução

3. Conclusão Homologação

4. Go-Live

5. Encerramento

   
   

➡️ Metodologia e repositório de scripts

1. Metodologia: Scrum, Kanban, etc (especificar)

2. Ferramenta de acompanhamento: (Jira, trello, etc)

3. Repositório: Github

   
   

➡️ Fluxo do processo

Utilizei o site (gratuito) https://app.diagrams.net/ para criar o diagrama

Exemplo:

🗣️ Etapa 2: Entendimento do Projeto com a Área de Negócios

Perguntas para a área de negócio:

1. Qual é o objetivo principal do projeto?

2. Quais decisões serão tomadas com base nesses dados?

3. Quais são as dores com o processo atual?

4. Quais são os indicadores (KPIs) mais importantes?

5. Quais são as métricas de cálculo dos indicadores?

6. Quem são os usuários finais do painel?

7. Qual o nível de detalhe esperado?

8. Glossário dos termos do negócio

Nome	Conceito
Exemplo: ATM	ATM (Automated Teller Machine) caixa eletrônico, é um terminal de autoatendimento bancário instalado em agências ou locais públicos.

9. Dados Sensíveis

   O projeto possui dados sensíveis? Justifique o uso.

10. Quem pode acessar os dados?

11. É necessário inserir segurança de controle de acesso por usuário?

12. Quais filtros são considerados importantes para visualização dos dados?

13. Existe alguma outra observação que você gostaria de pontuar?

    
    

📌 Sempre valide com a área de negócio o que é considerado “correto” ou “esperado” para cada métrica.

🗣️ Etapa 3: Dados e atualizações

1. Existe alguma fonte de dados disponível? (API, servidor, arquivo txt, csv, Excel ou outros)

2. Há necessidade de exportação dos dados ou integração com outros sistemas?

3. A cada atualização, precisamos trazer todos os dados novamente ou apenas os novos/alterados?

   ☐Full Load: Reprocessa toda a base de dados (mais simples, porém mais pesado)

   ☐ Incremental Load: Apenas os dados novos ou modificados são trazidos (requer chave ou coluna de controle, como data_modificacao, data_inclusao, id, rowversion etc.)

4. Informe a frequência em que o dado é atualizado na origem.

   ☐Em tempo real

   ☐A cada 60 minutos

   ☐ 1x por dia

   ☐ 1x por semana

   ☐ Quinzenal

   ☐ Mensal

   ☐ Trimestral

5. Existe alguma informação que indique quando o dado foi criado ou alterado? Explique.

6. Qual o tempo necessário de base história deverá ser mantida?

   ☐hora ☐ Diário ☐Semanal ☐Quinzenal ☐Mensal ☐Trimestral ☐Semestral ☐Anual

   ☐Outro (Justifique).

7. Existe algum campo que nunca se repete e identifica cada linha de forma única (PK) para cada registro? Algo que nunca se repete, como um número de pedido, matrícula ou protocolo? Explique e nomeie os campos.

8. Existe alguma outra observação relevante sobre os dados?

Exemplo do formulário para auxiliar a etapa inicial

📊 Etapa 3: Planejamento da Arquitetura (Refinamento técnico)

➡️ Fonte dos dados

Nome da Fonte	Tipo	Origem	Formato	Acesso
Planilha de Vendas	Arquivo	Enviado via e-mail	.xlsx	Pasta compartilhada / SharePoint
Cadastro de Clientes	Banco	Sistema de CRM	Tabela SQL	Conexão ODBC: crm_db.clientes
Cadastro de Produtos	Banco	ERP (Oracle)	Tabela SQL	Conexão Oracle: erp.produtos
Calendário	Tabela Local	Tabela gerada em script	.csv	Local ou gerada por script de data

➡️ Frequência da carga

Fonte	Frequência	Horário de Atualização	Observações
Vendas (planilha)	Diária (manual)	Até 09h00	E-mail automático do sistema de vendas
Clientes (CRM)	Diário (automático)	05h00	Full Load
Produtos (ERP)	Diário (automático)	05h00	Full Load
Calendário	Única (estática)	-	Script Python para geração até 2030

➡️ Estrutura dos dados (camanda medalhão, bronze (stage), silver (ods) e camada ouro (dm_BI)

Tudo vai depender da necessidade do negócio mas neste caso, na camada stage será a carga incremental (comente novos registros), na camada ODS ficará o operacional, dado bruto contendo o histórico completo e os dados nos tipos corretos, exemplo, coluna de data, estará formatada como data, número como número, etc. É a famosa tabela tabelão!

Na camada DW falaremos mais para frente, mas é onde ficarão as nossas tabelas fato com as dimensões de filtro agregado ao invés de um tabelçao como na camada ODS.

Utilizarei procedures para levar os dados de camda a camada.

➡️ Tabelas envolvidas

Nome da Tabela	Fonte	Chaves	Comentário
stage_vendas	Planilha Excel	id_venda	Ingestão bruta
stage_clientes	CRM (SQL Server)	id_cliente	Importação direta
stage_produtos	ERP (Oracle)	id_produto	Apenas produtos ativos

➡️ Regras de negócio e tratamentos necessários

Regra de Negócio	Aplicação
Não considerar vendas com valor total = 0	Filtro em stage_vendas
Clientes com estado nulo serão marcados como 'IGNORAR'	Regra em dim_cliente
Produto descontinuado será mantido para histórico	Nenhum filtro aplicado
Datas devem ter FK válida na dim_data	Carga rejeita datas inválidas
Vendas duplicadas (mesmo ID) são ignoradas	duplicação por id_venda

➡️ Caminho do dado

Exemplo:

Planilha Excel (.xlsx)

↓

Carga manual via script Python (ETL)

↓

Tabela stage_vendas

↓

Transformações, deduplicações

↓

Tabela fato_vendas (com FKs)

↓

Power BI conectado ao DM

➡️ Organização da Documentação no Projeto

/📁pasta

├── 01. Discovery (todo o material que recebermos das áreas envolvidas)

├── 02. Delivery (entrega final)

├── 03. Documentação (este arquivo word, diagramas, etc)

├── 04. Python

├── 05. T-SQL

└── 00. Integração

└── 01. Stage

└── 01. Table - Controle de Processamento.sql

└── 02. Table - Estrutura_Stage - Saldo.sql

└── 02. ODS

└── 01. Table - Saldo.sql

└── 02. Procedure - Carga table Saldo.sql

└── 03. DM

└── 01. Table - dimData.sql

└── 02. Table - dimOcorrencias.sql

└── 03. Table - dimFilial.sql

├── 06. SSIS (Integration Service)

├── 07. SSAS (Analysis Services)

├── 08. Power BI

└── 01. Relatórios

└── 02. Script TMDL

➡️ Ferramentas e linguagens utilizadas

ETL: SSIS (Visual Studio)

Banco de dados: SQL Server (Servidor BI)

Linguagens: SQL e Python

Visualização: Power BI

➡️ Governança e segurança

Quem pode acessar os dados?

Quais são as camadas de acesso?

➡️ Diagrama

Criei o diagrama gratuitamente no site: https://dbdiagram.io/d/

🛠️ Etapa 4: Desenvolvimento e Documentação técnica

➡️ Dados alocados em: Nome servidor BI ➡️ Schema: Nome schema

➡️ Tabelas - Camada Stage e ODS (INPUT)

Para cada tabela de stage, documente:

• Nome da tabela

• Origem dos dados

• Descrição de cada coluna

• Tipo de dado

• Observações (formato, nulos, padrões, etc.)

📄 Exemplo: Documentação Técnica da Camada Stage (faça isso para todas as tabelas)

Tabela: stage_vendas

Coluna	Tipo de dado	Descrição
id_venda	INT	Identificador único da venda
data_venda	DATE	Data em que a venda foi realizada
id_produto	INT	Chave estrangeira para produto
id_cliente	INT	Chave estrangeira para cliente
valor_total	DECIMAL(10,2)	Valor total da venda

➡️ Camada DM - DataMart (Output)

1. Qual tipo de modelagem utilizada?

☒ Estrela   ☐ Floco de Neve   ☐ 3FN  ☐Data Vault

2. Quais são as tabelas de dimensões?

Nome da Tabela	Tipo	Comentário
DimData	Dimensão	Calendário completo: dia, mês, ano, feriados, semana, etc.
DimStatusK7	Dimensão	Status/classificações do processo K7.
DimOcorrencias	Dimensão	Tipos de ocorrência, categorias e descrições.
DimFilial	Dimensão	Informações da filial: código, nome, cidade, UF, regional.
DimCicloContabil	Dimensão	Períodos/fechamentos contábeis: ciclo, competência, ano fiscal.
DimIdK7	Dimensão	Identificadores e atributos do K7 (chaves e metadados).
DimIdATM	Dimensão	Identificação do ATM/terminal: código, localização, tipo, status.
DimTipoNotas	Dimensão	Denominações/tipos de cédulas (ex.: R$ 10, R$ 20, R$ 50, etc.).

3. Qual o relacionamento entre as tabelas e quais são as chaves primárias e chaves secundárias de cada tabela fato?

4. Quais são as tabelas fato?

5. Diagrama DM

Utilizei o site https://app.diagrams.net/ para fazer o diagrama abaixo, mas também poderia usar o Microsoft Power Point, Paint, canvas, figma, etc.

Algumas ferramentas para auxiliar

Ferramenta	Foco	Gratuito?	Link
diagrams.net	Diagramas em geral	✅ 100%	https://www.drawio.com/
dbdiagram.io	ERD a partir de código	✅ Sim	https://dbdiagram.io/d/
Lucidchart	Apresentações e colaboração	⚠️ Parcial	https://www.lucidchart.com
Creately	Visuais corporativos diversos	⚠️ Parcial	https://creately.com
Whimsical	Fluxos e UX	⚠️ Parcial	https://whimsical.com
Figma	Design e prototipagem colaborativa (inclui fluxos e diagramas)	✅ Sim (versão free)	https://www.figma.com
Canva	Design gráfico e diagramas simples	✅ Sim (versão free)	https://www.canva.com