Cómo documentar un conjunto de datos correctamente

Introducción: un archivo de datos no se explica por sí solo

La documentación, los metadatos, la trazabilidad, la calidad y la reproducibilidad determinan si un conjunto de datos puede utilizarse con confianza meses después de haber sido creado. Un archivo CSV puede abrirse sin errores y, aun así, producir conclusiones equivocadas porque nadie sabe qué representa cada fila, de dónde proceden sus cifras o qué significa una celda vacía.

En Ciencia de Datos, documentar correctamente un dataset significa entregar junto con los registros la información necesaria para interpretarlos, validarlos, reutilizarlos y conocer sus límites. No basta con una lista de columnas: hace falta explicar el contexto de generación, las reglas de inclusión, el momento al que corresponden las observaciones, el significado de las variables y los controles que realmente se han realizado.

Esta guía propone un procedimiento aplicable a archivos CSV, tablas extraídas de bases de datos y otros conjuntos tabulares de trabajo. Incluye una ficha mínima, un diccionario de variables, ejemplos de reglas verificables, una propuesta de organización de archivos y un caso práctico de solicitudes de soporte. El objetivo no es producir documentación extensa, sino conseguir que otra persona pueda tomar el conjunto de datos y trabajar con él sin depender de explicaciones de memoria.

Índice de contenidos

Qué significa documentar un dataset y cómo se diferencia de otros documentos

Un conjunto de datos es una colección delimitada de observaciones preparada para un propósito: estudiar incidencias, comparar ventas, entrenar un modelo, verificar un indicador o elaborar un informe. Puede estar guardado como archivo, particionado en varios ficheros o expuesto mediante una tabla o vista. Su documentación debe describir la versión concreta que se va a consumir, no solamente la base de datos o la aplicación de la que procede.

Conviene distinguir cuatro niveles que suelen confundirse:

• Documentación de los datos de una organización: explica conceptos compartidos, responsables, sistemas y definiciones de negocio. Su alcance es transversal y se desarrolla con más detalle en cómo documentar correctamente los datos de una empresa.
• Catálogo de datos: ayuda a descubrir qué conjuntos existen y dónde encontrarlos. Una ficha de catálogo puede enlazar al dataset, pero no sustituye sus instrucciones de interpretación. Véase cómo construir un catálogo corporativo de datos.
• Documentación de un proyecto de Ciencia de Datos: cubre problema, hipótesis, decisiones analíticas, experimentos y resultados. Se relaciona con el dataset, pero responde a preguntas diferentes; esta separación se desarrolla en cómo documentar completamente un proyecto de Ciencia de Datos.
• Documentación del propio dataset: fija qué entrega se está usando, qué contienen sus registros, cómo se construyó, qué pruebas superó y para qué usos es o no es adecuada.

Por ejemplo, una empresa puede definir de forma corporativa qué es una «solicitud atendida». Pero un dataset exportado para analizar tiempos de respuesta necesita precisar, además, si incluye solicitudes anuladas, qué fechas abarca, si los registros son históricos o un estado actual, y si las reaperturas crean filas nuevas.

Regla práctica: si una respuesta puede cambiar entre dos entregas del mismo conjunto, esa respuesta tiene que quedar identificada en la documentación de la versión entregada.

1. Dar identidad y finalidad al conjunto de datos

La primera pieza es una ficha legible que permita responder «qué es», «para qué sirve», «quién responde por él» y «cuál es la versión examinada». Sin esta identificación se termina trabajando con archivos como datos_final_3_definitivo.csv, nombres que no demuestran nada sobre el contenido.

Campos mínimos de la ficha

El identificador se mantiene mientras el concepto del conjunto sea reconocible. La versión cambia cuando cambia la entrega, su contenido o el contrato de interpretación. El nombre del fichero debe ayudar, pero no es el único mecanismo de identidad.

Escribir una finalidad precisa

«Análisis de datos» no describe una finalidad. «Calcular la distribución del tiempo transcurrido hasta la primera respuesta de las solicitudes abiertas entre enero y junio de 2026» sí delimita una pregunta. Esa frase obliga a aclarar qué es «primera respuesta», cuándo comienza el reloj y qué solicitudes entran en el análisis.

La finalidad también ayuda a fijar las exclusiones. Un archivo suficiente para calcular tiempos agregados puede ser inadecuado para estudiar causas de resolución, porque no conserva motivos, cambios intermedios ni interacciones con el cliente. Que un dataset tenga muchas columnas no significa que sirva para cualquier pregunta.

2. Definir población, unidad de observación y reglas de selección

Antes de explicar las columnas hay que responder una cuestión más importante: ¿qué representa exactamente una fila? En un archivo de ventas puede ser un pedido, una línea del pedido, un producto facturado o una combinación de cliente y mes. En cada caso las sumas y los promedios se interpretan de una manera diferente.

La granularidad debe expresarse con una frase inequívoca

Ejemplo: «Cada fila representa una solicitud de soporte distinta, creada durante el periodo seleccionado, con su situación conocida a la fecha de corte». Esa definición implica que una misma solicitud no debe aparecer dos veces, aunque haya tenido varias conversaciones o cambios de estado.

Si el conjunto se compone de eventos, la definición cambia: «Cada fila representa un cambio de estado de una solicitud». Confundir ambas granularidades puede multiplicar falsamente el número de solicitudes cuando se cuentan filas.

Documentar el universo y sus filtros

La ficha debe describir la población de referencia, el periodo de observación y las condiciones concretas de inclusión y exclusión:

• Incluidos: solicitudes creadas entre el 1 de enero y el 30 de junio de 2026, con identificador válido y pertenecientes al servicio analizado.
• Excluidos: registros de prueba identificados por una marca formal, solicitudes duplicadas confirmadas por una regla definida y registros de otros servicios.
• Conservados aunque incompletos: solicitudes sin primera respuesta o todavía abiertas al corte, porque eliminarlas sesgaría la medición.
• Unidad y clave: una fila por solicitud, identificada mediante id_solicitud.

Hay una diferencia importante entre no cumplir un criterio de inclusión y tener un dato ausente. Si una solicitud está abierta, su tiempo hasta el cierre puede ser desconocido, pero ello no justifica excluirla silenciosamente. La decisión depende del análisis previsto y debe documentarse.

Explicar el sesgo de cobertura

Un dataset procedente únicamente del formulario web no representa necesariamente todas las incidencias de la organización: podrían existir llamadas, correos directos o visitas presenciales. La documentación debe explicitar esta limitación y, cuando sea posible, cuantificar el alcance de la fuente.

La cobertura no se resuelve afirmando que «son todos los datos disponibles». Debe señalarse todos respecto a qué población, canal, periodo y sistema.

3. Documentar las fechas, los cortes y el significado temporal

Muchos errores de análisis provienen de utilizar una fecha que parece evidente, pero no lo es. Una solicitud puede tener fecha de creación, de primera respuesta, de modificación, de cierre y de extracción. Cada una describe un acontecimiento distinto.

Distinguir periodo analizado, fecha de corte y fecha de generación

• Periodo de creación: intervalo en el que se originaron las observaciones seleccionadas.
• Fecha de corte: momento hasta el cual se considera conocido el estado del proceso.
• Fecha de extracción: momento en que se obtuvo el archivo; puede ser posterior al corte.
• Fecha de carga: momento en que una aplicación o repositorio recibió la entrega; no sustituye a las anteriores.

Si el archivo se genera el 16 de julio con un corte al 15 de julio, cualquier modificación posterior al corte debe excluirse de los campos «al corte» o identificarse expresamente. De lo contrario, dos extracciones hechas días diferentes pueden atribuir estados distintos a una misma fecha histórica.

Fechas civiles, marcas de tiempo y zonas horarias

Un campo de fecha como 2026-07-15 puede representar un día de calendario de España y no un instante universal. Una marca como 2026-07-15T16:20:00Z sí representa un instante en UTC. La documentación debe indicar cuál de los dos conceptos se utiliza y, para registros horarios, la zona y el formato.

Cuando un evento se almacena en UTC y se muestra en hora local de Europe/Madrid, un cambio de día puede alterar el agrupamiento diario. Para calcular una duración, es preferible restar instantes correctamente normalizados; no restar cadenas de texto ni horas locales sin considerar los cambios de horario.

Datos de estado frente a datos de eventos

Un dataset de estado responde «cómo estaba cada solicitud el día del corte». Otro, basado en eventos, responde «qué cambios ocurrieron y cuándo». El primero suele ser cómodo para informes; el segundo permite reconstruir trayectorias, si el historial es completo. No se debe afirmar que se pueden estudiar reaperturas si solo existe un estado final.

En modelos predictivos aparece un riesgo adicional: fuga de información. Una variable que solo se conoce al final del proceso no puede usarse para simular una predicción realizada al abrir una solicitud. La ficha debe distinguir cuándo pasa a estar disponible cada campo.

4. Describir archivos, formatos y estructura de entrega

Una documentación útil permite abrir el dataset sin adivinar configuraciones regionales ni recorrer carpetas hasta encontrar el archivo correcto.

Información física imprescindible

• Formato: CSV, Parquet, JSON, tabla o vista, indicando variante cuando importe.
• Codificación: por ejemplo, UTF-8.
• Separador y decimal: en un CSV, coma para campos y punto para decimales, si esa es la convención real.
• Encabezados: presencia de fila de cabecera y nombres exactos de los campos.
• Fechas: formato ISO y, si hay horas, zona temporal.
• Vacíos: representación del nulo; por ejemplo, un campo CSV vacío, no el texto literal NULL.
• Archivos relacionados: varios fragmentos, tablas auxiliares, catálogos de códigos o un manifiesto de particiones.
• Volumen: número de filas y columnas de esa versión, tamaño aproximado y fecha del recuento.

Para formatos columnarios, también conviene indicar la versión del esquema, los tipos lógicos y las reglas de particionado. Para tablas remotas, debe constar la consulta o vista reproducible y el estado del origen al realizar la extracción.

Establecer nombres estables

Los nombres deben ser previsibles y comparables: solicitudes_estado_2026-07-15_v1.csv comunica mejor su contenido que exportacion_nueva.csv. Sin embargo, la fecha en el nombre no aclara por sí sola si es la fecha de corte, de ejecución o de publicación. Esa relación debe quedar escrita.

Cuando haya múltiples ficheros particionados, es imprescindible precisar cómo se relacionan: si las particiones no se solapan, qué clave permite detectar duplicados y si la suma de registros corresponde al total declarado.

5. Crear un diccionario de datos que explique realmente las columnas

El diccionario es el centro de la documentación de un conjunto tabular. Su función no es repetir nombres, sino describir qué mide cada variable, cómo se obtuvo, cuáles son sus valores válidos y qué interpretaciones quedan fuera.

Qué debe tener cada campo

1. Nombre exacto: coincide con la cabecera real del archivo.
2. Descripción: definición que pueda entender alguien ajeno a la extracción.
3. Tipo lógico: texto, entero, decimal, fecha, fecha-hora, booleano o categoría; distinto del tipo de almacenamiento cuando corresponda.
4. Unidad y escala: euros, horas naturales, porcentaje de 0 a 100, proporción de 0 a 1, etcétera.
5. Dominio de valores: categorías permitidas, límites, patrones o referencias a un catálogo.
6. Obligatoriedad y nulos: cuándo puede faltar y por qué.
7. Origen o cálculo: campo del sistema original, derivación o regla de transformación.
8. Disponibilidad temporal: desde qué momento del proceso se conoce el valor.
9. Observaciones: excepciones, cautelas o cambios históricos importantes.

No todos los datasets necesitan decenas de atributos por columna, pero ningún campo crítico debería quedar descrito como «identificador», «importe» o «fecha» sin contexto.

Ejemplo de diccionario compacto

Fijarse en horas_primera_respuesta: «tiempo de respuesta» sería demasiado ambiguo. ¿Cuenta fines de semana? ¿Incluye respuestas automáticas? ¿Qué ocurre si no hay respuesta? ¿Se redondea antes o después de calcular? La documentación completa debe resolverlo.

Diferenciar identificadores de números con los que se opera

Que un identificador esté compuesto por dígitos no significa que sea una magnitud. La media de un código postal, de una referencia de cliente o de un número de expediente carece de sentido. Declarar estos campos como texto también ayuda a conservar ceros iniciales.

6. Explicar ausencias, unidades, escalas y categorías

Los errores más difíciles de descubrir no siempre son valores manifiestamente imposibles. A veces son valores técnicamente válidos a los que se atribuye un significado equivocado.

Un nulo no tiene una única interpretación

En un dataset pueden convivir ausencias por causas muy diferentes:

• No ocurrido todavía: no hay fecha de cierre porque la solicitud sigue abierta.
• No aplicable: un descuento no corresponde a cierto tipo de operación.
• No registrado: el hecho ocurrió, pero no se capturó su valor.
• Desconocido: el sistema no puede confirmar el dato.
• Suprimido: el dato se excluyó por una regla de privacidad o control de acceso.

Cuando estas situaciones afectan a la interpretación, conviene mantener indicadores auxiliares o un código de motivo de ausencia. No debe convertirlas todas automáticamente en cero. Un tiempo de primera respuesta desconocido no equivale a una respuesta inmediata.

Unidades y denominadores

«Importe» exige moneda, tratamiento de impuestos y criterio de redondeo. «Duración» exige unidad y calendario. «Tasa» exige numerador y denominador; por ejemplo, solicitudes respondidas sobre solicitudes elegibles, no necesariamente sobre todas las filas.

Un valor 0.18 puede significar 18 % o 0,18 %. Especificar «proporción en el intervalo de 0 a 1» elimina esa duda. Para los porcentajes deben indicarse además criterios de exclusión de registros del denominador.

Catálogos y códigos

Una variable prioridad que admite 1, 2 y 3 necesita una tabla de equivalencias. También es importante señalar si los códigos cambiaron con el tiempo. Un 2 puede representar algo distinto en un sistema antiguo y uno nuevo.

La documentación debe registrar cuándo un valor está realmente fuera del dominio. Inventar equivalencias para «arreglar» categorías sin confirmación funcional puede hacer que el dataset parezca más limpio a costa de perder veracidad.

7. Registrar la procedencia y cómo se construyó la entrega

La procedencia describe el camino que siguieron los datos desde sus fuentes hasta el archivo final. La pregunta clave es: ¿podría otra persona reconstruir la misma versión, o al menos explicar por qué no puede hacerlo?

Documentar la cadena de preparación

Para cada etapa importante hay que identificar entrada, operación y salida:

1. Fuente: aplicación, tabla, vista o archivo de origen, con su identificador y responsable.
2. Selección: filtros, columnas solicitadas, ventanas temporales y exclusiones.
3. Unión: claves, cardinalidades esperadas y decisiones ante coincidencias múltiples.
4. Transformación: conversiones de zona horaria, normalizaciones, deduplicación y campos derivados.
5. Validación: pruebas ejecutadas y resultado concreto.
6. Publicación: ruta o repositorio, fecha, versión y persona o proceso responsable.

Si el dataset se extrae de una base de datos empresarial, es útil conservar la consulta utilizada y la versión del procedimiento de extracción. Para profundizar en la conexión entre fuentes operativas y análisis, puede consultarse cómo integrar Ciencia de Datos con bases de datos empresariales.

Registrar decisiones irreversibles

Eliminar duplicados, agrupar operaciones, redondear importes o convertir eventos en estados puede hacer que la información original no sea recuperable desde la entrega. Esas decisiones requieren una explicación especial: qué criterio se utilizó, cuántos registros afectó y dónde se conserva la fuente, si puede conservarse legítimamente.

La frase «se limpiaron los datos» no es reproducible. «Se excluyeron registros marcados como pruebas; se eligió la última versión por identificador según la fecha de actualización; los empates se enviaron a revisión» permite entender y auditar la transformación.

Qué guardar para reproducir

• Script de extracción o preparación, si existe, con su versión o revisión.
• Parámetros de ejecución, incluidas fechas de corte y filtros.
• Versión de los catálogos utilizados para interpretar códigos.
• Recuento de entradas y salidas por etapa.
• Identificador de los datos de origen o instantánea, cuando sea posible.
• Hash criptográfico del fichero final para comprobar integridad byte a byte.

Un hash no demuestra que los datos sean correctos; solo permite detectar si dos ficheros tienen el mismo contenido binario con un grado muy alto de confianza. Por eso complementa, pero no sustituye, las pruebas semánticas.

8. Documentar la calidad con pruebas y resultados, no con adjetivos

Etiquetar un dataset como «depurado» o «fiable» aporta poca información si no se sabe qué se comprobó. La documentación debe distinguir reglas exigidas, resultados medidos y problemas conocidos.

Controles básicos según el uso

Por ejemplo, «37 valores ausentes en horas_primera_respuesta entre 800 solicitudes (4,625 %)» es una medida concreta. Pero hay que distinguir cuántas de esas 37 solicitudes no tenían respuesta al corte y cuántas tenían un fallo de registro. La métrica por sí sola no revela la causa.

La mejora del dato en origen es otro proceso y debe abordarse con criterios propios: cómo mejorar la calidad de los datos antes de automatizar procesos.

Ejemplo de validación reproducible con Python

El siguiente script, reducido deliberadamente a controles esenciales, comprueba la estructura y varias invariantes del CSV descrito en esta guía. Utiliza únicamente la biblioteca estándar de Python. Su función es demostrar cómo convertir reglas documentadas en comprobaciones; no certifica por sí solo toda la calidad del conjunto.

import csv
from datetime import date
from decimal import Decimal, InvalidOperation
from pathlib import Path

RUTA = Path("datos/solicitudes_estado_2026-07-15_v1.csv")
CAMPOS = [
    "id_solicitud", "fecha_apertura_local",
    "estado_al_corte", "fecha_cierre_local",
    "horas_primera_respuesta",
]
INICIO = date.fromisoformat("2026-01-01")
FIN = date.fromisoformat("2026-06-30")
CORTE = date.fromisoformat("2026-07-15")

vistos = set()
errores = []
total = 0
sin_primera_respuesta = 0

with RUTA.open("r", encoding="utf-8", newline="") as f:
    lector = csv.DictReader(f, delimiter=",")
    if lector.fieldnames != CAMPOS:
        raise ValueError("Cabecera distinta del contrato documentado")

    for numero_fila, fila in enumerate(lector, start=2):
        total += 1
        id_solicitud = fila["id_solicitud"]
        estado = fila["estado_al_corte"]

        if not id_solicitud or id_solicitud in vistos:
            errores.append((numero_fila, "Identificador vacío o repetido"))
        vistos.add(id_solicitud)

        try:
            apertura = date.fromisoformat(fila["fecha_apertura_local"])
            if not INICIO <= apertura <= FIN:
                errores.append((numero_fila, "Apertura fuera del periodo"))
        except (TypeError, ValueError):
            apertura = None
            errores.append((numero_fila, "Fecha de apertura inválida"))

        if estado not in {"abierta", "cerrada"}:
            errores.append((numero_fila, "Estado fuera de dominio"))

        cierre_texto = fila["fecha_cierre_local"]
        if (estado == "cerrada") != bool(cierre_texto):
            errores.append((numero_fila, "Estado y fecha de cierre incoherentes"))
        if cierre_texto:
            try:
                cierre = date.fromisoformat(cierre_texto)
                if cierre > CORTE or (apertura and cierre < apertura):
                    errores.append((numero_fila, "Fecha de cierre incoherente"))
            except ValueError:
                errores.append((numero_fila, "Fecha de cierre inválida"))

        horas = fila["horas_primera_respuesta"]
        if horas == "":
            sin_primera_respuesta += 1
        else:
            try:
                valor = Decimal(horas)
                if not valor.is_finite() or valor < 0:
                    errores.append((numero_fila, "Duración inválida"))
            except (InvalidOperation, TypeError):
                errores.append((numero_fila, "Duración no numérica"))

print(f"Registros: {total}")
print(f"Sin primera respuesta registrada: {sin_primera_respuesta}")
print(f"Incidencias de validación: {len(errores)}")
for numero, descripcion in errores[:20]:
    print(f"Fila {numero}: {descripcion}")
if errores:
    raise SystemExit("La validación no se ha superado")

El script parte de un contrato muy concreto: archivo CSV con coma como separador, codificación UTF-8, cabeceras exactas, fechas de calendario ISO, ausencia representada por campo vacío y duración numérica con punto decimal. Si el productor utiliza otras reglas, deben modificarse juntos el contrato y el código. Además, el script no reconstruye eventos ni demuestra que se haya calculado correctamente la primera respuesta: esas comprobaciones requieren acceso al origen o controles adicionales.

Un control importante para una entrega real es el recuento de conciliación: comparar el número de solicitudes seleccionadas en origen, las eliminadas por cada filtro, las rechazadas y las exportadas. Superar las validaciones fila por fila no garantiza que no falten miles de registros.

9. Caso práctico: documentar un dataset de solicitudes de soporte

Supongamos que una pequeña empresa quiere analizar el tiempo de primera respuesta de sus solicitudes. El conjunto se prepara a partir de un sistema interno y se entrega al área que realiza el análisis. Los nombres y registros de este ejemplo son ficticios y se utilizan exclusivamente para ilustrar el método.

El contrato de interpretación

Se fija por escrito lo siguiente:

• Objetivo: describir las horas naturales hasta la primera respuesta humana.
• Población: solicitudes del servicio incluidas en el origen y abiertas desde el 1 de enero hasta el 30 de junio de 2026.
• Granularidad: exactamente una fila por solicitud, incluso si se reabrió.
• Corte: situación y respuestas conocidas hasta el 15 de julio de 2026, inclusive.
• Estado: únicamente abierta o cerrada al corte; anulaciones y pruebas se tratan según exclusiones documentadas.
• Duración: horas naturales transcurridas entre instantes de apertura y primera respuesta humana, calculadas a partir de eventos con hora normalizada; valor decimal no negativo, redondeado a dos decimales al exportar.
• Ausencia: horas vacías cuando no consta una primera respuesta humana hasta el corte; ese vacío no equivale a cero.
• Limitación: el archivo contiene fechas locales, no las marcas temporales originales de los eventos; por ello no permite recalcular con precisión horaria la duración desde sus propias columnas.

Ejemplo de archivo CSV

Una muestra inventada, sin datos personales y reducida para facilitar su lectura, podría ser:

id_solicitud,fecha_apertura_local,estado_al_corte,fecha_cierre_local,horas_primera_respuesta
S-1001,2026-01-12,cerrada,2026-01-14,2.50
S-1002,2026-03-05,abierta,,
S-1003,2026-05-18,cerrada,2026-05-20,0.75
S-1004,2026-06-29,abierta,,5.25

El registro S-1002 no tiene cierre ni primera respuesta al corte. El registro S-1004 sigue abierto, pero ya recibió respuesta. Es importante conservar esa distinción: una solicitud abierta no equivale necesariamente a una solicitud sin respuesta.

Preguntas que la documentación permite contestar

Con la ficha y el diccionario se puede saber qué solicitudes entran en el cálculo, qué hacer con los valores ausentes y cuál es la fecha que delimita el estado. También se puede evitar una comparación incorrecta: medir la primera respuesta en horas naturales no equivale a medir el cumplimiento de un compromiso expresado en horas laborables.

Preguntas que siguen abiertas

La documentación no debe aparentar capacidades inexistentes. Esta entrega no permite explicar el número de reaperturas, analizar la duración de cada conversación, estudiar el contenido de los mensajes ni reconstruir la primera respuesta a partir de eventos. Para esas preguntas habría que obtener otros datos y probablemente trabajar con otra unidad de observación.

Un ejemplo de informe de validación

En una entrega real conviene acompañar el archivo de una pequeña tabla de evidencias. Las cifras siguientes son meramente ilustrativas; no corresponden a una ejecución del script sobre un archivo existente.

Este último resultado ilustra una regla importante: un control pendiente debe aparecer como pendiente, no como conforme. La documentación gana credibilidad al revelar lo que todavía no está comprobado.

10. Organizar la documentación como parte de la entrega

La documentación es más útil cuando viaja junto al conjunto de datos y permite orientarse sin instalar una herramienta particular. Para un proyecto pequeño basta con una estructura sencilla, mientras que en proyectos mayores estas piezas pueden almacenarse en un repositorio o catálogo con control de versiones.

Estructura de carpetas recomendada

dataset-solicitudes/
├── README.md
├── datos/
│   └── solicitudes_estado_2026-07-15_v1.csv
├── documentacion/
│   ├── diccionario.csv
│   ├── origen-y-transformaciones.md
│   ├── limitaciones.md
│   └── cambios.md
├── controles/
│   ├── validar_dataset.py
│   └── resultados-validacion.md
└── manifest.sha256

La estructura es una propuesta, no una obligación técnica. Lo fundamental es que exista una puerta de entrada, que las referencias funcionen y que los resultados de comprobación pertenezcan a la misma versión que el archivo entregado.

Ejemplo de README mínimo

Un README bien escrito puede tener menos de una página y ahorrar numerosas reuniones. Este ejemplo es una plantilla ilustrativa, no una ficha certificada:

# Solicitudes de soporte: estado al 2026-07-15

ID: soporte_solicitudes_estado
Versión: 1.0.0
Generación: 2026-07-16
Corte: 2026-07-15

## Propósito
Describir los tiempos de primera respuesta humana de
solicitudes abiertas entre enero y junio de 2026.

## Unidad de observación
Una fila por solicitud. Clave: id_solicitud.

## Archivo
Datos: datos/solicitudes_estado_2026-07-15_v1.csv
Formato: CSV, UTF-8, coma, punto decimal.
Nulos: campo vacío.

## Fuente y transformaciones
Consultar documentacion/origen-y-transformaciones.md

## Variables
Consultar documentacion/diccionario.csv

## Validación
Ejecutar: python controles/validar_dataset.py
Resultados: controles/resultados-validacion.md

## Límites
No reconstruye eventos ni reaperturas.
No emplear para evaluar rendimientos individuales.

## Responsables
Funcional: responsable del servicio de soporte.
Técnico: responsable de la extracción.

Para una distribución real hay que sustituir las descripciones genéricas de responsables por canales de contacto o roles operativos identificables dentro de la organización. No es necesario incluir teléfonos personales, contraseñas ni rutas internas sensibles en materiales destinados a terceros.

Guardar un manifiesto de integridad

Puede calcularse una huella SHA-256 del archivo para comprobar si sus bytes cambian. En Linux, por ejemplo:

sha256sum datos/solicitudes_estado_2026-07-15_v1.csv > manifest.sha256
sha256sum -c manifest.sha256

La segunda orden debe ejecutarse desde la carpeta base de la entrega. Para proteger el valor de la comprobación, el manifiesto de referencia debe conservarse en un medio o proceso de confianza; si cualquiera puede modificar a la vez el archivo y su manifiesto, el hash no proporciona autenticidad frente a manipulaciones intencionadas.

11. Registrar privacidad, seguridad, permisos y usos no autorizados

Un dataset no debe distribuirse porque «solo contiene datos de trabajo». Puede incorporar referencias de clientes, registros que permitan identificar a trabajadores, conversaciones, ubicaciones o atributos delicados. Incluso cuando se sustituyen nombres por códigos, los registros pueden seguir siendo datos personales si existe posibilidad razonable de reidentificación.

Preguntas para la ficha de acceso

• ¿Contiene datos personales o información empresarial confidencial?
• ¿Qué perfiles pueden acceder al archivo completo y cuáles necesitan una versión reducida?
• ¿Qué campos se han eliminado por minimización y bajo qué criterio?
• ¿La entrega está anonimizada de forma efectiva o solo seudonimizada?
• ¿Puede publicarse, compartirse con proveedores o utilizarse con herramientas externas?
• ¿Qué base o autorización permite cada uso, cuando resulte necesaria?
• ¿Cuál es el plazo y el procedimiento de conservación o eliminación?
• ¿Qué limitaciones contractuales, licencias o derechos se aplican a datos de terceros?

La ficha no necesita reproducir todas las políticas de la organización; sí debe indicar las restricciones aplicables a esta entrega concreta y dónde se encuentran las políticas autorizadas. Hay criterios adicionales en cómo compartir datos entre aplicaciones de forma segura.

Distinguir reproducibilidad y divulgación

Es perfectamente posible documentar un proceso para que sea auditable internamente sin publicar los datos de origen ni los secretos de acceso. Un repositorio puede incluir la lógica de transformación y ejemplos sintéticos, mientras que las tablas reales permanecen en un entorno protegido.

Los logs de validación también merecen atención: no deberían imprimir filas completas con datos confidenciales para explicar errores. Es preferible registrar un identificador técnico, tipo de incidencia y posición de la fila, manteniendo la información sensible bajo controles apropiados.

12. Controlar versiones, cambios de significado y mantenimiento

Un dataset es una entrega fechada, pero también puede formar parte de una serie recurrente. Si se exporta cada semana, la documentación debe permitir distinguir dos tipos de cambio: los que modifican los valores observados y los que modifican la manera de interpretarlos.

Cambios que obligan a revisar el contrato

• Se añade, elimina o cambia de nombre una columna.
• Se redefine una categoría o cambia el significado de un estado.
• Se modifica la población cubierta o la regla de deduplicación.
• Se cambia el criterio temporal o el calendario usado para calcular duraciones.
• Se corrige una fuente y se vuelven a publicar observaciones históricas.
• Se modifica la precisión, escala o representación de los valores ausentes.

Una convención posible es separar cambios incompatibles de esquema o significado, ampliaciones compatibles y correcciones que mantienen el contrato. Si se utilizan números como 1.0.0, la organización debe explicar qué implica cada componente. No basta con asumir que todo el mundo interpreta igual los números de versión.

Un registro de cambios útil

El ejemplo muestra por qué una ampliación que en teoría sería compatible puede afectar a consumidores con validación estricta de columnas. La compatibilidad siempre debe comprobarse con el software real que lee el archivo.

Vincular cada versión con sus evidencias

Una entrega reproducible debe conservar una relación inequívoca entre archivo, diccionario, transformación, pruebas, limitaciones y fecha de aprobación. Un diccionario actualizado meses después, sin indicar a qué versión se refiere, puede ser tan peligroso como no tener diccionario.

También conviene declarar quién revisa la documentación cuando cambia la fuente y quién tiene autoridad para publicar una versión corregida. El documento debe mantenerse al ritmo del dato, no depender de una gran revisión anual.

13. Errores frecuentes y lista de comprobación antes de entregar

Errores que parecen menores y afectan a todo el análisis

• Documentar solo nombres y tipos: el analista sigue desconociendo qué significa cada registro.
• Omitir los filtros: no se sabe qué población representan los resultados.
• Confundir fecha de extracción y de corte: se interpretan estados como si pertenecieran a otro momento.
• Tratar todos los nulos como cero: se alteran medias, tasas e indicadores.
• No distinguir porcentajes y proporciones: aparecen errores de escala.
• Ignorar la granularidad: una unión duplica filas y falsea agregados.
• Declarar «sin errores» sin especificar pruebas: se transmite una seguridad injustificada.
• Guardar la documentación fuera del paquete: los ficheros circulan sin su contexto.
• Actualizar columnas sin cambiar el diccionario: el contrato deja de describir el archivo.
• Confundir seudonimización con anonimización: se autorizan usos o accesos sin evaluación suficiente.

Comprobación final en diez preguntas

1. ¿Puede una persona nueva identificar el dataset y su versión sin preguntar a quien lo generó?
2. ¿Sabe qué representa una fila y cuál es la clave esperada?
3. ¿Conoce la población, el periodo, las inclusiones y las exclusiones?
4. ¿Distingue las fechas de evento, corte, extracción y publicación?
5. ¿Dispone de definiciones para todos los campos críticos?
6. ¿Entiende las unidades, categorías y causas de las ausencias?
7. ¿Puede seguir el origen y las transformaciones relevantes?
8. ¿Puede revisar las pruebas ejecutadas y los fallos o controles pendientes?
9. ¿Conoce las restricciones de acceso, conservación y reutilización?
10. ¿Puede relacionar el archivo con el diccionario, los resultados de validación y el registro de cambios correctos?

Si alguna respuesta es negativa, no es imprescindible redactar un manual entero. Suele bastar con completar la pieza que falta, verificarla con el responsable correspondiente y probar la entrega con una persona que no haya participado en la extracción.

La mejor prueba: una lectura independiente

Antes de declarar terminado el trabajo, conviene entregar el paquete a alguien ajeno a su preparación y pedirle tres tareas: describir la población, calcular un indicador sencillo respetando los nulos y señalar una limitación. Si la persona necesita explicaciones verbales esenciales, la documentación todavía tiene lagunas.

La cantidad de páginas producidas no es el indicador más importante. Lo es la posibilidad de tomar decisiones técnicas correctas a partir de una versión identificable y verificable.

Preguntas frecuentes sobre documentación de conjuntos de datos

Conclusión: documentar los datos es hacer explícitas sus condiciones de uso

Un dataset correctamente documentado no necesita prometer perfección. Necesita explicar con precisión qué contiene, qué no contiene, cómo se obtuvo, qué significan sus variables, qué controles se realizaron y cuáles son sus límites. Esa información convierte una exportación puntual en un recurso que puede revisarse y reutilizarse con criterio.

El procedimiento más sólido empieza por la unidad de observación y el alcance, continúa con un diccionario claro, registra el contexto temporal y la procedencia, y termina vinculando las pruebas y las restricciones a una versión concreta. Cuando esta disciplina forma parte de la preparación habitual, se reducen las interpretaciones improvisadas y resulta más fácil mantener análisis consistentes aunque cambien las personas o las herramientas.