Lección 11 de 20 · Lectura y práctica
Generar Documentación Automatizada con dbt Docs
Concepto claveLa 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.
Del concepto a la práctica
Taller de esta lección
La documentación automatizada reúne metadatos del proyecto, modelos, columnas y tests en una representación navegable. Su utilidad depende de que las descripciones expliquen significado y límites, no de que exista una página generada.
Ejemplo resuelto
Para fct_orders, una descripción útil dice: tabla a nivel de línea de pedido, excluye cancelaciones y expresa line_total en la moneda de origen. La columna order_id se describe como identificador de la orden, no como “ID”.
Pruébalo
Añade descripción al modelo y a tres columnas importantes.
Indica granularidad, filtros y unidad monetaria.
Asocia los tests definidos al modelo.
Genera la documentación y busca el modelo por su nombre.
Comprueba tu resultado
Error frecuente: documentar una tabla agregada como si conservara una fila por transacción. Corrígelo escribiendo la granularidad en la primera frase y revisando el SQL.
Ejercicio: documenta un modelo con dos columnas, order_id y line_total, usando los registros A,10 y B,15. Resultado esperado: la documentación identifica la granularidad, la moneda o ausencia de moneda, el cálculo de line_total y los tests visibles; una consulta de control verifica aparte dos filas y suma 25; no afirma una suma por cliente que el modelo no contiene.
Ejecuta dbt docs generate para producir los artefactos documentales; dbt docs serve permite revisarlos localmente cuando tu entorno lo admite. El conteo de filas depende del catálogo y del adaptador: generar documentación no sustituye reconciliar la tabla con una consulta explícita.

Mapa de prácticaAntes de analizar, comprueba los tipos, valores vacíos, duplicados y unidades. Decide cómo tratar cada problema según el contexto y conserva la trazabilidad del cambio. Un gráfico solo es útil si los datos de entrada son coherentes.
Ver la infografía en tamaño completo ↗Fuentes para profundizar
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:
- Escribes documentación en archivos YAML (schema.yml) o usando comentarios en modelos SQL
- Ejecutas
dbt docs generatepara compilar la documentación - Ejecutas
dbt docs serveo usas dbt Cloud para visualizar el sitio web - 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 1DESPUES: 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.
- Abre tu proyecto dbt y localiza el modelo
marketing_funnelenmodels/marts/ - Crea o edita el archivo
schema.ymlen la misma carpeta - 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
marketingyconversion
- Genera la documentación con
dbt docs generate - Verifica en dbt Docs que:
- La descripción aparece correctamente
- El lineage muestra fuentes correctas
- Las columnas documentadas tienen tooltips
Pistas
- 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.
Sigue con Modelado de Datos en dbt Cloud: Tests, Documentación y Práctica
Esta lección forma parte de un curso de Cursalo. Revisa su programa y elige entre la compra individual o el acceso a toda la escuela.
Si ya tenías acceso a este curso, entra con tu cuenta: tus derechos y tu progreso se conservan. No necesitas comprarlo de nuevo.