7 práticas recomendadas para a documentação de dados

A documentação de dados não apenas organiza melhor o trabalho de profissionais da Ciência de Dados, mas pode fazer sua empresa economizar tempo e dinheiro

Em 2017, o Github realizou uma pesquisa a fim de avaliar os principais problemas encontrados no desenvolvimento de software de código aberto. E uma de suas principais descobertas foi que o maior complicador apontado pelos desenvolvedores em sua plataforma foi a presença de uma “documentação incompleta ou confusa”.

Documentar dados é basicamente registrar ou relatar uma informação em detalhes, seja com apoio de citações ou referências, ou mesmo de evidências ou provas. Em outras palavras, o objetivo da documentação de dados é coletar informações sobre os dados para facilitar a compreensão, interpretação, transformação, uso e transmissão dessas informações. 

Atualmente, com o grande volume de dados dentro das empresas, a documentação não é apenas uma necessidade, mas uma obrigação para organizações que lidam todos os dias com um grande volume de dados. 

Além disso, é importante entender que o processo de documentação de dados deve começar logo no início de um projeto e continuar sendo realizado durante todo o processo. Isso facilita a documentação e tornará menos provável que você esqueça algum tipo de detalhe, garantindo que as pessoas que vierem depois de você poderão interpretar, avaliar e repetir seu trabalho com perfeição. 

A seguir, você entende porque a documentação de dados é tão importante, e algumas práticas recomendadas para aplicar esta estratégia no dia a dia da sua empresa. 

Por que a documentação de dados é tão importante?

O processo de documentação de dados deve ser realizado já no início do desenvolvimento. Muitas equipes de Ciência de Dados ou TI pensam na documentação como algo que é feito mais tarde, quando os dados estão perfeitamente estruturados e organizados. Mas se esperarmos até que tudo esteja “perfeito” para implementar as melhores práticas, estamos fazendo um grande desserviço ao negócio. É preciso documentar as fontes de dados e modelos à medida que você cria seu stack. Isso ajudará a empresa a alcançar uma cultura de dados sólida e ideal.

É preciso dizer que a documentação de dados fornece à sua empresa benefícios que ela não receberia de outra forma. Entre eles, uma melhor cultura data-driven, a economia de tempo e recursos e o aumento da transparência nos negócios. 

Economia de tempo e dinheiro

Ao documentar seus dados antecipadamente, você reduz aquilo que chamamos de “dívida tecnológica”. Ou seja, ao invés de olhar para trás depois que o stack foi construído e tentar lembrar o que todos os seus dados significam, você pode documentar essas informações à medida que avança no projeto. 

Afinal, todos os motivos por trás de suas ações ainda estão frescos em sua mente, o que facilita na documentação e fornece uma maior riqueza de detalhes aos profissionais que virão depois de você. Isso economiza tempo de suas equipes e, consequentemente, dinheiro para sua empresa.

Maior transparência

Ao documentar todos os seus conjuntos de dados, qualquer pessoa na empresa terá uma janela para os dados disponíveis e as informações que vêm com eles. Isso não apenas gera menos dúvidas sobre o que pode ou não ser feito, mas também permite que engenheiros e analistas de dados tenham maior autonomia no tratamento e análise desses dados, sem precisar ir atrás de seus proprietários sempre que forem usá-los. Ao documentar, você deixa essas informações sempre ali, disponíveis para consulta.

Garantia de dados de alta qualidade

Não há nada mais importante do que a qualidade dos seus dados. E ao documentá-los, você garante que eles sejam utilizados e interpretados da maneira correta. Dessa forma, os KPIs serão consistentes entre os modelos, e as alterações de código poderão ser rastreadas sempre que preciso. Ou seja, com a documentação fica muito mais fácil acompanhar cada atualização dos conjuntos de dados, assim como possíveis erros e dependências entre os modelos.

7 boas práticas recomendadas para a documentação de dados

Agora que você entende a importância da documentação de dados, deve saber que não existe uma fórmula ou receita única para realizar essa documentação no seu projeto de Ciência de Dados. Em geral, as necessidades variam de empresa para empresa, equipe para equipe, e projeto para projeto.

Em outras palavras: não se trata apenas de produzir uma documentação de modelo de ciência de dados. O que você deve se perguntar é o que precisa documentar e, mais importante do que isso, por quê?

Depois disso, fica mais fácil definir as metas de documentação e começar a trabalhar neste objetivo. Para auxiliar neste processo, trouxemos a seguir 7 boas práticas na hora de realizar a documentação de dados em sua empresa. 

 

1. Documente com um propósito

O primeiro passo para construir sua documentação de dados é responder às seguintes perguntas:

• Quem vai consumir esta documentação?

• Por que eles precisam dessa documentação?

• Como eles gostariam de consumir a documentação?

 

Isso ajudará você a pensar no propósito dessa documentação, ou melhor, enxergar o processo de forma ampla. A ideia é criar a melhor opção possível desse modelo de documentação, a fim de atender melhor às necessidades das partes interessadas. Sem ter isso em mente, fica muito difícil começar.

 

2. Crie um guia de estilo 

O próximo passo é criar o seu próprio guia de estilo para a documentação de dados. Para isso, é preciso detalhar os diferentes códigos e convenções de nomenclatura que você deseja seguir. Isso dará a você a as pessoas que lerão sua documentação um padrão a ser seguido. Assim, toda vez que surgir uma pergunta em relação ao modelo de dados, é possível voltar para o guia e respondê-la sem maiores problemas.

Para um bom resultado, o seu guia de estilo precisa conter:

 

• Convenções de nomenclatura;

• Práticas recomendadas de SQL (comentários de código, CTEs, subconsultas etc.);

• Padrões de documentação para seus modelos;

• Tipos de dados de colunas de data, carimbo de data/hora e moeda;

• Padrões de fuso horário para todas as datas.

 

Este é apenas um exemplo: você pode criar o seu, de acordo com as necessidades das suas equipes e da empresa em questão.

3. Comece seu projeto com um propósito claro

Imagine criar uma documentação do zero, com todo o cuidado necessário, para perceber que ninguém precisa dela? Para ajudar a mitigar esse risco e desenvolver algo que realmente vá ajudar outras pessoas, inicie todo projeto com um objetivo claro.

Para isso, é preciso:

 

• Documentar os objetivos de negócios da empresa ou cliente;

• Definir como seu projeto de ciência de dados atenderá a essas necessidades;

• Definir uma visão para seu projeto ou produto, a fim de orientar a equipe na direção certa;

• Criar métricas de avaliação claras para que você possa determinar objetivamente se o projeto foi bem-sucedido;

• Fazer uma análise de custo-benefício pode ajudar a determinar a aprovação/não aprovação do projeto;

• Documentar tudo aquilo que você não deseja realizar.

 

4. Desenvolva um plano de projeto inicial suficiente

O “plano de projeto” é pensado para definir itens importantes durante o processo de documentação. Por exemplo: recursos, datas de entrega, orçamento e financiamento, riscos e contingências, entre outros. A dica aqui é não exagerar, mas planejar com antecedência suficiente para executar o projeto com eficiência. Isso dará a você uma compreensão mais sólida do trabalho inicial, e ajudará na questão da documentação de dados. 

 

Importante: o plano de projeto deve ser dimensionado com o tamanho e a complexidade de um projeto de verdade. Mesmo que pareça pequeno ou simples, anotar algumas considerações básicas e uma lista de etapas pode ajudar você a conceituar melhor sua abordagem. 

 

5. Documente as definições de coluna ao construir um modelo

Já explicamos por que documentar seus dados à medida que você cria seus modelos de dados ajuda a economizar tempo. Porém, isso também ajudará a aumentar a qualidade de seus dados. Isso porque, ao criar definições para suas colunas, você garante que elas sejam consistentes e precisas. 

A recomendação é documentar seus dados diretamente no dbt. Além disso, ferramentas de catálogo de dados, como o Castor, ajudam a levar essa documentação um passo adiante. 

6. Use o controle de versão com seus modelos de dados

O controle de versão é uma importante prática de engenharia de software, que você pode decidir incorporar ao seu fluxo de trabalho de análise. Atualmente, a maioria das equipes usa o Github para acompanhar as alterações feitas em qualquer código, porém você pode utilizar outras ferramentas, como o dbt e o Prefect. Elas facilitam a exibição da documentação junto com o código realizado.

 

O Prefect, por exemplo, é uma ferramenta baseada em Python, que possui uma interface de usuário limpa e simples. Ao implantar um pipeline usando a interface do usuário, você pode adicionar um arquivo LeiaMe, que fica ao lado do código de execução do pipeline.

 

7. Considere usar um modelo pré-criado

Por fim, se você achar que isso facilitará seu processo de documentação de dados, é possível fazer uso de modelos já existentes, que ajudarão você a começar. Alguns deles são:

 

• CRISP-DM: trata-se do ciclo de vida de ciência de dados mais comum, e define uma série de documentos que você deve desenvolver ao longo de um projeto de mineração de dados. Esses documentos tendem a uma visão mais tradicional de documentação extensa. Você pode visitar a página Github da Patiegm para obter um modelo de documentação CRISP-DM.

• TDSP da Microsoft: a Microsoft adota uma abordagem de documentação mais moderna em seu Team Data Science Process . Neste sentido, os modelos Charter e Exit Report são bastante úteis, mesmo que você não use o TDSP.

• Cartões modelo: em 2019, o Google introduziu o conceito de cartão de modelo para definir uma visão para relatórios de modelo padronizados e transparentes. Para saber mais, visite withgoogle.com.

Conclusão

Deu para perceber que a documentação de dados é algo muito importante, certo? E apesar de não ser a parte mais “divertida” do trabalho, é realmente necessária.

Quando você se concentra na documentação, as partes interessadas podem tomar decisões mais rápidas e melhores, e as equipes de dados experimentam menos atrito ao tentar realizar o trabalho. Em outras palavras: facilita a vida de todos os envolvidos. Portanto, não adie mais a documentação de dados, pois isso só vai gerar mais trabalho para você e suas equipes no futuro. Priorize aquilo que é importante agora!