Concepto clave

Documentar un proyecto de analytics es como crear un manual de instrucciones para una maquinaria compleja. Imagina que eres el ingeniero que diseña una planta de produccion: no solo construyes las maquinas, sino que tambien documentas como funcionan, como se conectan entre si y que hacer si algo falla. En dbt Cloud, la documentacion no es un lujo, es una herramienta de productividad que permite a todo el equipo entender el lineage (linaje) de los datos, desde las fuentes crudas hasta los modelos listos para analisis.

La documentacion efectiva responde tres preguntas fundamentales: ¿Que hace este modelo? ¿De donde vienen sus datos? ¿Como se relaciona con otros elementos del proyecto? Cuando documentas correctamente, reduces el tiempo de onboarding de nuevos miembros, facilitas la depuracion de errores y creas un activo reutilizable. Piensa en ello como la diferencia entre heredar una casa con planos detallados versus heredarla con solo las llaves.

Como funciona en la practica

Vamos a documentar un proyecto de analytics que transforma datos de ventas. Supongamos que tienes tres modelos: stg_orders (datos crudos de pedidos), dim_customers (dimension de clientes) y fct_sales (hechos de ventas). El proceso tiene cuatro pasos:

Definir descripciones en los archivos .yml para cada modelo, fuente y columna.
Usar docs generate en dbt Cloud para compilar la documentacion.
Navegar por el lineage visual en la interfaz web.
Compartir la URL de documentacion con el equipo de analytics.

Por ejemplo, al documentar fct_sales, describiras que calcula ventas netas, especificaras que depende de stg_orders y dim_customers, y anotaras columnas clave como revenue o order_date. Esto crea un mapa interactivo que muestra como fluyen los datos.

Codigo en accion

Aqui tienes un ejemplo de como se ve la documentacion en un archivo schema.yml, mostrando el antes y despues:

# ANTES: Sin documentacion
models:
  - name: fct_sales
    columns:
      - name: revenue
      - name: order_id

# DESPUES: Con documentacion completa
models:
  - name: fct_sales
    description: Tabla de hechos que agrega ventas por cliente y fecha, utilizada para reportes de desempeno.
    columns:
      - name: revenue
        description: Ingresos totales por venta, calculados como cantidad * precio unitario despues de descuentos.
        tests:
          - not_null
      - name: order_id
        description: Identificador unico del pedido, sirve como llave foranea a la tabla de pedidos.

Y aqui un ejemplo de como definir fuentes documentadas:

sources:
  - name: raw_data
    description: Datos crudos extraidos de nuestra base de datos operacional.
    tables:
      - name: orders
        description: Tabla de pedidos del sistema ERP, actualizada diariamente.
        columns:
          - name: customer_id
            description: ID del cliente que realizo el pedido.

Errores comunes

Documentar solo al final del proyecto: Esto lleva a descripciones incompletas o desactualizadas. Solucion: Documenta cada modelo segun lo creas, como parte del flujo de trabajo.
Usar descripciones vagas como "tabla de ventas" en lugar de "agrega ventas diarias por region con metricas de crecimiento". Solucion: Sigue la regla de que una descripcion debe decir el proposito y el contexto.
Olvidar documentar las fuentes de datos: Sin esto, el lineage queda incompleto. Solucion: Incluye siempre secciones sources en tus archivos .yml.
No actualizar la documentacion al refactorizar: Si cambias un modelo pero no su descripcion, generas confusion. Solucion: Trata la documentacion como codigo, revisala en cada cambio.
Ignorar las pruebas (tests) en la documentacion: Los tests como not_null o unique son parte de la documentacion de calidad. Solucion: Anotalos claramente en las columnas.

Checklist de dominio

Cada modelo en tu proyecto tiene una descripcion clara en archivos .yml.
Todas las columnas clave estan documentadas con su proposito y calculo.
Las fuentes de datos estan definidas y descritas, mostrando el origen de la informacion.
El lineage visual en dbt Cloud muestra conexiones completas entre modelos.
Puedes explicar a un colega como usar un modelo solo con la documentacion.
La documentacion se genera y actualiza automaticamente con cada ejecucion.
Has compartido la URL de documentacion con al menos un miembro del equipo.

Documenta un Proyecto de Analytics de Ventas en dbt Cloud

En este ejercicio, practicaras documentar un proyecto realista de analytics. Sigue estos pasos:

Prepara tu entorno: Abre dbt Cloud y crea un nuevo proyecto o usa uno existente. Asegurate de tener al menos tres modelos: uno de staging, uno dimensional y uno de hechos.
Escribe descripciones: Edita los archivos schema.yml de tu proyecto. Para cada modelo, agrega una descripcion que explique su proposito en 1-2 oraciones. Luego, documenta al menos 5 columnas clave, incluyendo detalles como calculos o fuentes.
Define fuentes: Si tu proyecto usa fuentes externas, crea una seccion sources en un archivo .yml. Describe la fuente y sus tablas, anotando columnas importantes.
Genera y revisa: Ejecuta dbt docs generate en dbt Cloud. Navega a la pestaña de Documentation y verifica que tus descripciones aparezcan. Usa el lineage visual para confirmar que las dependencias se muestran correctamente.
Comparte y valida: Copia la URL de la documentacion y enviasela a un companero (o simula esto revisandola tu mismo). Asegurate de que pueda entender el flujo de datos sin explicaciones adicionales.

Objetivo: Al final, tu proyecto debe tener documentacion completa que permita a cualquier analytics engineer entender su estructura y uso.

Pistas

Si no tienes un proyecto propio, usa el ejemplo de fct_sales del contenido y crea modelos similares en un entorno de prueba.
Recuerda que las descripciones en YAML usan indentacion de 2 espacios; un error comun es mezclar tabs y espacios.
Para ver el lineage, haz clic en un modelo en la documentacion y busca el grafico de dependencias.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Práctica: Documentar un Proyecto Completo de Analytics