El problema
Documentar modelos de datos suele caer en una de dos trampas. La primera: no documentar nada, porque "ya se entiende del código" o "después lo hacemos". La segunda: documentar todo con descripciones que no aportan nada.
Si tenés un campo que se llama lead_id y la descripción dice "ID del lead", no agregaste información. Eso ya se infiere del nombre. Lo que falta es el contexto que alguien de afuera no tiene: de dónde viene ese ID, qué formato tiene, qué significa en el negocio, qué pasa si viene nulo.
Documentar lo obvio es contraproducente. Genera ruido, ocupa espacio, y da la falsa sensación de que el modelo está documentado cuando en realidad no hay información útil.
Documentar para quien no conoce el contexto
La documentación debería pensarse como texto para alguien que no estuvo en las reuniones, que no conoce el sistema de origen, que no sabe por qué se tomaron ciertas decisiones. Puede ser un analista nuevo, un equipo de otra área, o vos mismo dentro de seis meses.
Eso cambia el nivel de exigencia del texto. Ya no alcanza con poner el nombre del campo con otras palabras. Hay que agregar contexto funcional, de negocio o técnico que no sea evidente del código.
Para campos donde hay lógica de negocio involucrada (cálculos, filtros, reglas de transformación), es fundamental que la documentación explique qué se hizo y por qué. Si un campo tiene un cálculo que depende de una regla de negocio, esa regla tiene que estar documentada. Si un filtro excluye ciertos registros, tiene que estar claro cuáles y por qué.
Qué documentar
No hace falta documentar todo. Pero hay cosas que siempre conviene documentar:
Campos con lógica de negocio. Si el valor de un campo depende de un cálculo, una regla o una transformación que no es obvia, documentá qué se hizo. "Monto neto calculado como monto bruto menos impuestos, usando la alícuota vigente al momento de la transacción" es útil. "Monto neto" solo, no.
Campos que vienen de sistemas externos. Si un campo viene de un CRM, un ERP o cualquier sistema que no controlás, documentá de dónde viene, qué formato tiene, y qué suposiciones estás haciendo sobre él. Esto conecta directamente con lo que vimos sobre testear suposiciones: si documentás qué asumís, es más fácil saber qué testear.
Campos con valores codificados. Si un campo tiene valores como 1, 2, 3 que representan estados o categorías, documentá qué significa cada valor. O mejor: tené una tabla de referencia y documentá que existe.
Relaciones entre tablas. Si una tabla se relaciona con otra por una clave, documentá esa relación. Especialmente si la relación tiene condiciones (solo registros activos, solo del último año, etc.).
Decisiones que no son obvias. Si elegiste hacer algo de una manera particular por una razón específica, documentá esa razón. "Se usa la fecha de creación en lugar de la fecha de modificación porque el sistema de origen no actualiza la fecha de modificación de forma confiable" es información valiosa.
Documentación y gobierno
La documentación es parte del gobierno de datos. Si no sabés qué significa un campo, no podés gobernar quién debería tener acceso a él. Si no sabés de dónde viene un dato, no podés determinar quién es el owner. Si no sabés qué lógica tiene un cálculo, no podés validar si el resultado es correcto.
Esto conecta con lo que vimos sobre ownership: el dato tiene que tener un dueño, y ese dueño tiene que poder explicar qué significa. La documentación es el registro de esa explicación.
También conecta con la calidad. Si documentás qué suposiciones estás haciendo sobre un campo (que es único, que no es nulo, que tiene ciertos valores válidos), estás explicitando qué deberías testear. La documentación y los tests se refuerzan mutuamente.
Documentación que termina en un catálogo
Si tu organización tiene (o va a tener) un catálogo de datos, la documentación que escribís al desarrollar debería pensarse como texto para el consumidor final de ese catálogo.
Eso significa que no es solo para el equipo técnico. Es para el usuario de negocio que quiere entender qué datos tiene disponibles, de dónde vienen, y si puede confiar en ellos.
Cuando pensás la documentación así, el nivel de exigencia sube. Ya no alcanza con notas internas que solo entiende quien las escribió. Tiene que ser texto que alguien de otra área pueda leer y entender sin necesidad de preguntarle al equipo de datos.
Documentación viva
La documentación que no se actualiza pierde valor rápidamente. Si cambia la lógica de un campo y la documentación sigue diciendo lo anterior, es peor que no tener documentación: genera confusión activa.
Por eso conviene que la documentación viva cerca del código. Si está en el mismo repositorio, en el mismo archivo de configuración, es más probable que se actualice cuando cambia la lógica. Si está en un documento separado, en otra herramienta, es más probable que quede desactualizada.
Esto también conecta con lo que vimos sobre tests que pierden vigencia. Así como los tests pueden dejar de ser válidos cuando cambia el negocio, la documentación puede dejar de ser correcta. Hay que revisarla periódicamente, especialmente cuando hay cambios en los modelos.
Cierre de la colección
Este artículo cierra una serie sobre calidad, gobierno y confiabilidad. Los temas están conectados:
- La calidad no es un módulo aparte; se decide en cada etapa del pipeline.
- Los tests validan suposiciones sobre los datos, no solo que el código corra.
- El dato tiene que tener un dueño con nombre y apellido, no un área difusa.
- Frenar el pipeline ante un fallo de calidad es una decisión de gobierno, no un detalle técnico.
- La decisión entre monorepo y multi-repo en transformación es de gobierno: priorizar consistencia entre dominios o autonomía de equipos.
- La documentación que agrega valor es la que permite entender qué significa un dato sin necesidad de preguntar.
Todos estos puntos apuntan a lo mismo: construir confianza en los datos. Confianza de que los números reflejan la realidad. Confianza de que cuando algo falla, hay alguien que se hace cargo. Confianza de que cuando alguien necesita entender un dato, puede hacerlo. Confianza de que las métricas de un dominio cierran con las de otro porque comparten las mismas definiciones.
Esa confianza no se construye con herramientas. Se construye con prácticas: testear lo que asumís, documentar lo que no es obvio, definir quién responde por cada dato, decidir qué hacer cuando algo falla, y elegir estructuras de proyecto que reflejen las prioridades de gobierno de tu organización.
La documentación es la última pieza de ese rompecabezas. Sin ella, todo lo demás queda incompleto. Con ella, el gobierno de datos deja de ser una aspiración y empieza a ser algo que funciona.