Generar Documentación Automatizada con dbt Docs

Concepto clave

La documentación automatizada en dbt Docs es como tener un arquitecto que dibuja planos actualizados de tu edificio de datos cada vez que construyes algo nuevo. En lugar de mantener manualmente diagramas y descripciones, dbt genera automáticamente un sitio web interactivo que muestra cómo se relacionan tus modelos, qué columnas contienen y qué pruebas están asociadas.

Imagina que trabajas en un equipo de analytics donde diferentes personas crean modelos SQL. Sin documentación automatizada, tendrías que preguntar constantemente: "¿Qué hace esta tabla?" o "¿De dónde viene esta columna?". Con dbt Docs, cada modelo, fuente y semilla queda documentado a través de comentarios en código YAML, creando un single source of truth que siempre está sincronizado con tu código.

Cómo funciona en la práctica

El proceso sigue estos pasos:

1. Escribes documentación en archivos YAML (schema.yml) o usando comentarios en modelos SQL
2. Ejecutas dbt docs generate para compilar la documentación
3. Ejecutas dbt docs serve o usas dbt Cloud para visualizar el sitio web
4. Compartes el enlace con tu equipo para colaboración

Por ejemplo, cuando documentas un modelo de customer_lifetime_value, defines su propósito, describe cada columna (como customer_id, total_purchases, avg_order_value) y especificas las pruebas aplicadas. dbt Docs luego muestra esto junto con un gráfico de lineage que traza las dependencias desde las fuentes hasta los modelos finales.

Codigo en accion

ANTES: Modelo sin documentación

-- models/marts/customer_lifetime_value.sql
SELECT 
    customer_id,
    COUNT(order_id) as total_orders,
    SUM(amount) as total_spent
FROM {{ ref('stg_orders') }}
GROUP BY 1

DESPUES: Modelo con documentación en schema.yml

# models/marts/schema.yml
version: 2

models:
  - name: customer_lifetime_value
    description: "Calcula el valor de vida del cliente basado en historial de pedidos"
    columns:
      - name: customer_id
        description: "Identificador único del cliente, enlaza con dimensiones de cliente"
        tests:
          - not_null
          - unique
      - name: total_orders
        description: "Número total de pedidos realizados por el cliente"
      - name: total_spent
        description: "Suma total gastada por el cliente en todos los pedidos"
        tests:
          - accepted_values:
              values: ['>0']

Errores comunes

• Documentación desactualizada: Modificar modelos sin actualizar YAML. Solución: Integra revisiones de documentación en tu proceso de PR.
• Descripciones vagas: Usar "ID del cliente" en lugar de "Identificador único, enlaza con tabla dim_customers". Solución: Sigue un template de documentación.
• Falta de contexto empresarial: No explicar por qué existe el modelo. Solución: Incluye sección business_logic en descripciones.
• Ignorar lineage: No documentar fuentes o semillas. Solución: Documenta todo el pipeline, no solo modelos finales.
• No usar tags: Perder capacidad de filtrar documentación. Solución: Aplica tags como finance, marketing, sales a modelos.

Checklist de dominio

• Puedo generar y servir dbt Docs localmente con CLI
• Documenté al menos 3 modelos con descripciones y columnas en YAML
• Agregué pruebas (tests) a columnas documentadas
• Verifiqué que el lineage muestra correctamente las dependencias
• Compartí el enlace de dbt Cloud Docs con un compañero
• Usé tags para organizar modelos en la documentación
• Actualicé documentación después de un cambio en un modelo

Documentar un modelo de funnel de conversión

En este ejercicio, documentarás un modelo existente de funnel de conversión para hacerlo comprensible para el equipo de marketing.

1. Abre tu proyecto dbt y localiza el modelo marketing_funnel en models/marts/
2. Crea o edita el archivo schema.yml en la misma carpeta
3. Documenta el modelo con:
   • Descripción clara del propósito empresarial
   • Documentación de al menos 5 columnas clave
   • Aplica 2-3 pruebas a columnas importantes
   • Añade tags marketing y conversion
4. Genera la documentación con dbt docs generate
5. Verifica en dbt Docs que:
   • La descripción aparece correctamente
   • El lineage muestra fuentes correctas
   • Las columnas documentadas tienen tooltips

• Usa el bloque models: en YAML, no confundas con sources:
• Para pruebas en columnas, revisa la sintaxis de accepted_values o relationships
• Si no tienes un modelo marketing_funnel, crea uno simple con 3-4 columnas primero

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.