Cómo documentar una base de datos para facilitar su mantenimiento

Introducción

La documentación de una base de datos debe explicar qué significan sus tablas y columnas, cómo funcionan sus relaciones y dónde se aplican sus reglas. Un listado de nombres y tipos puede describir la estructura, pero no aclara por qué existe cada dato, qué significa un valor nulo o qué se rompería al modificar una columna.

Estas preguntas aparecen durante tareas muy concretas: corregir una importación, añadir un campo obligatorio, revisar un informe, sustituir una aplicación o mantener una base que creó otra persona. Cuando las respuestas dependen de recuerdos y suposiciones, una modificación pequeña puede alterar silenciosamente el significado de la información.

Documentar una base de datos para facilitar su mantenimiento consiste en conservar ese contexto junto con la descripción verificable del modelo. No exige escribir un manual exhaustivo antes de empezar, sino construir una referencia que permita comprender el dato y evaluar los cambios.

El alcance aquí es la base lógica y su comportamiento: entidades, campos, relaciones, restricciones, vistas, rutinas, flujos de información y evolución del esquema. El servidor, las rutas del sistema operativo y la configuración del motor pertenecen a otro nivel. Los ejemplos corresponden a una aplicación ficticia de asistencia técnica; no deben interpretarse como un modelo obligatorio para todas las empresas.

Índice

• Distinguir documentación del dato, de la base y del servidor
• Empezar por las preguntas que alguien necesitará resolver
• Crear una ficha de entrada a la base de datos
• Inventariar tablas indicando qué representa cada fila
• Construir un diccionario que explique significado y formato
• Documentar nulos, ceros, fechas y unidades sin ambigüedad
• Explicar claves, cardinalidades y comportamiento de las relaciones
• Registrar reglas de negocio y dónde se hacen cumplir
• Documentar vistas, rutinas, disparadores e índices por su propósito
• Registrar origen, transformaciones y consumidores del dato
• Extraer la estructura real sin confundirla con documentación completa
• Usar comentarios técnicos sin almacenar secretos
• Preparar un análisis de impacto antes de cambiar un objeto
• Caso práctico: hacer obligatorio un dato sin cambiar su significado
• Versionar documentación, esquema y migraciones de forma coordinada
• Qué puede automatizarse y qué necesita validación humana
• Incluir clasificación y ciclo del dato sin duplicar otras políticas
• Comprobar si la documentación sirve para mantener la base
• Preguntas frecuentes
• Conclusión

Distinguir documentación del dato, de la base y del servidor

La documentación se vuelve inmanejable cuando intenta reunir en un mismo lugar todos los detalles de una infraestructura. Conviene diferenciar qué se describe y enlazar los niveles, en lugar de repetir la misma información.

La base debe tener una referencia al servidor que la aloja, pero no necesita copiar cada puerto, volumen y unidad de servicio. Esa información se desarrolla en cómo organizar la documentación técnica de un servidor de bases de datos.

Del mismo modo, una ficha de tabla puede indicar el responsable funcional, pero no debe replicar todo el catálogo corporativo de datos. La separación permite actualizar cada nivel sin tener que corregir varias copias del mismo dato.

La documentación lógica debe permitir trabajar con la base aunque cambie su alojamiento. Si una migración de servidor obliga a reescribir el significado de todos los campos, probablemente se han mezclado detalles de infraestructura con reglas del modelo.

Empezar por las preguntas que alguien necesitará resolver

Antes de elegir una herramienta, identifica tareas de mantenimiento habituales. La estructura documental debería permitir responderlas con rapidez. Por ejemplo: ¿qué representa una fila?, ¿qué procesos escriben aquí?, ¿puede eliminarse este registro?, ¿qué informes consumen esta columna?, ¿qué significa un estado antiguo?

Estas preguntas sirven para priorizar. Una tabla pequeña que determina permisos o estados puede necesitar más explicación que una tabla muy grande con registros técnicos de significado evidente.

Documentar para cambios concretos

Imagina que alguien propone convertir una columna en obligatoria. Necesita saber qué significado tienen los nulos existentes, quién introduce el dato, qué importaciones lo omiten y qué versiones de la aplicación siguen permitiendo esa ausencia. Un simple diagrama de tablas no resuelve estas dudas.

Si se propone eliminar una tabla, necesitas conocer consumidores, tareas periódicas, relación con históricos y sustituciones realizadas. La ausencia de consultas recientes no prueba por sí sola que no exista una dependencia mensual o un procedimiento de recuperación que la utilice.

Documentar para explicar resultados

Una cifra de un informe puede depender de estados excluidos, fechas de corte y reglas de redondeo. Conservar estas decisiones evita «corregir» una consulta que estaba aplicando una definición de negocio deliberada.

La calidad documental se mide mejor por las preguntas que ayuda a resolver que por el número de páginas. Este enfoque encaja con crear documentación tecnológica sencilla, aplicado aquí al detalle del modelo de datos.

Crear una ficha de entrada a la base de datos

La ficha inicial debe explicar para qué existe la base y dónde comienza su responsabilidad. No es el diccionario completo, sino la puerta de entrada a sus documentos.

Base: asistencia
Finalidad: registrar solicitudes e intervenciones de soporte
Aplicación responsable: gestión interna de asistencia
Dominios principales: clientes, equipos e intervenciones
Fuente de autoridad: la aplicación valida las intervenciones
Fuera de alcance: contabilidad y documentos de facturación
Esquema funcional del ejemplo: servicio
Referencia de versión: migración 024 aplicada en el entorno revisado
Responsable funcional: operaciones de soporte
Responsable técnico: mantenimiento de la aplicación
Documentos asociados: diccionario, relaciones, reglas y cambios
Servidor y recuperación: referencias a sus documentos específicos

La versión «024» es un identificador ficticio de migración, no la versión del motor. Separar ambas referencias evita confundir la evolución del modelo con la actualización de PostgreSQL, MariaDB u otro sistema.

Incluye fecha de extracción técnica, fecha de validación funcional y entorno observado. Pueden ser diferentes: la estructura se puede haber extraído hoy y las reglas de negocio haberse revisado hace meses. Una sola fecha de modificación del archivo no expresa necesariamente ambas cosas.

La ficha también debe indicar si la documentación describe el estado actual, un diseño previsto o una situación histórica. Una propuesta pendiente no debe presentarse como garantía de lo que ya existe en producción.

Inventariar tablas indicando qué representa cada fila

La definición más importante de una tabla suele ser su granularidad: qué representa exactamente una fila. «Tabla de clientes» es insuficiente si puede contener personas, organizaciones, contactos o versiones históricas del mismo cliente.

En el ejemplo ficticio, la documentación inicial podría ser la siguiente:

Este inventario evita errores frecuentes al construir consultas. Si unes una intervención con cinco actuaciones y cuentas filas sin considerar la granularidad, puedes terminar contando cinco solicitudes en lugar de una.

También conviene clasificar las tablas por función: datos maestros, operaciones, históricos, datos derivados y áreas temporales. Esa clasificación orienta el mantenimiento, pero no autoriza a borrar una tabla por llamarse «temporal». Debe existir una regla real sobre qué puede reconstruirse y qué información es irrepetible.

La estructura general de la información se amplía en cómo estructurar datos empresariales útiles. La documentación debe registrar la granularidad que realmente tiene el sistema, aunque no coincida con el diseño que elegirías hoy.

Construir un diccionario que explique significado y formato

Un diccionario de datos describe columnas, pero su valor no está en repetir lo que el motor ya sabe. Además de tipo, longitud, nulabilidad y valor predeterminado, debe indicar significado, unidad, dominio de valores, origen y excepciones relevantes.

Este ejemplo resume varios campos de servicio.intervenciones. Los tipos se expresan con sintaxis ilustrativa de PostgreSQL; no se propone ejecutar una creación de tablas a partir de esta ficha.

Explicar aquello que el tipo no puede expresar

Un decimal no indica por sí mismo la moneda ni si incluye impuestos. Una fecha no explica si corresponde a creación, importación o hecho real. Un entero no informa de si su unidad son minutos, segundos o céntimos. Estas decisiones deben escribirse, especialmente cuando una columna se utiliza desde varios programas.

En este ejemplo la moneda es siempre EUR por una regla explícita del sistema ficticio. Incorporar otra moneda exigiría revisar el modelo y los consumidores. No bastaría con seguir guardando números bajo el mismo significado.

Usar nombres comprensibles sin reescribir la realidad

Si una columna se llama fecha2, documenta su nombre real y añade su significado funcional. Renombrarla puede ser una mejora futura, pero la documentación actual debe ayudar a localizarla tal como existe. No presentes un nombre ideal como si ya estuviera implementado.

Una convención coherente facilita el trabajo, como se explica en las normas para nombrar datos y documentos. Aun así, ningún nombre sustituye por completo a una definición precisa.

Documentar nulos, ceros, fechas y unidades sin ambigüedad

Muchos errores de mantenimiento nacen de interpretar valores aparentemente simples. Un nulo puede significar desconocido, no aplicable o pendiente; un cero puede ser una cantidad real. Si el sistema mezcla esos significados, la documentación debe reconocerlo y señalar la limitación, no ocultarla.

Un ejemplo con importes

En la aplicación ficticia, importe_acordado = NULL significa que el importe todavía no se ha acordado. El valor cero representa un servicio sin cargo adicional. Sustituir todos los nulos por cero produciría datos formalmente completos, pero cambiaría su significado.

La ficha debe explicar también qué tratamiento utilizan los informes. Excluir importes pendientes, mostrarlos separados o calcular un indicador de completitud son decisiones distintas. No deben quedar escondidas dentro de una función de sustitución de valores.

Instantes y fechas de negocio

Documenta el tipo utilizado, la convención de almacenamiento y la zona de presentación. En este ejemplo, los intercambios de instantes utilizan UTC y las pantallas pueden mostrarlos en la zona configurada. Una fecha de atención prevista, en cambio, podría representar un día de negocio sin hora: no es el mismo concepto.

El origen temporal también importa. Un registro importado puede tener una fecha del hecho y otra de recepción. Sobrescribir una con la otra impediría explicar por qué un evento antiguo llegó hoy.

Redondeo y acumulación

Si las actuaciones guardan minutos, define si son minutos reales, estimados o facturables, y cuándo se redondean. Redondear cada actuación antes de sumar puede dar un resultado diferente de sumar y redondear al final. La documentación debe conservar la regla aplicada por el sistema, no dejarla a la interpretación de cada informe.

Explicar claves, cardinalidades y comportamiento de las relaciones

Un diagrama de relaciones necesita algo más que líneas entre tablas. Debe indicar qué columnas enlazan, si la relación es obligatoria, cuántos registros puede haber a cada lado y qué ocurre cuando cambia o desaparece la entidad referenciada.

clientes          1 ─── 0..n intervenciones
intervenciones    1 ─── 0..n actuaciones
intervenciones    1 ─── 0..n historial_estados

equipos           1 ─── 0..n intervenciones
Cada intervención puede referirse a 0 o 1 equipo.

En el modelo ficticio, una intervención exige un cliente, pero puede existir sin equipo asociado. El diagrama debe expresar ambas cosas. Decir únicamente «equipos se relaciona con intervenciones» no permite saber si un nulo en esa referencia es un error.

Distinguir relación lógica y restricción implementada

Que dos campos se llamen cliente_id no demuestra que exista una clave foránea. Documenta si la relación está protegida por el motor, validada por la aplicación o simplemente asumida. Una relación sin restricción necesita una advertencia distinta de una relación garantizada.

Para cada clave foránea registra sus columnas y su acción ante borrado o actualización. La documentación de restricciones de PostgreSQL muestra que las restricciones y acciones referenciales deben expresarse de forma concreta; no basta con dibujar una relación.

Conservar el significado histórico

Si un equipo cambia de titular, la intervención anterior debe seguir asociada al cliente que contrató aquel servicio según las reglas del ejemplo. Por eso intervenciones.cliente_id no se obtiene retrospectivamente de la titularidad actual del equipo.

Esta decisión puede parecer redundante a quien solo observa columnas. Documentar el motivo evita que una «normalización» posterior elimine contexto histórico necesario. Las decisiones del modelo deben explicarse por su función, no defenderse únicamente porque ya existen.

Registrar reglas de negocio y dónde se hacen cumplir

Una regla documental debe permitir responder tres preguntas: qué condición se exige, dónde se comprueba y qué evidencia demuestra que sigue funcionando. «La información debe ser correcta» no es una regla verificable.

La tabla expresa un diseño del ejemplo. En una documentación real debes anotar si cada mecanismo está implementado, pendiente o existe solo en parte. Un documento no convierte una intención en una restricción técnica.

Comprobar el efecto real de una restricción

Por ejemplo, en PostgreSQL una condición CHECK puede admitir un resultado nulo. No debe confundirse una comprobación de rango con una obligación de presencia; la documentación oficial de restricciones de comprobación explica esta diferencia.

Estados y transiciones

El catálogo de estados debe definir significado y transiciones aceptadas. En el ejemplo, cerrar no equivale a cancelar, y reabrir exige conservar el evento de cierre previo. El valor actual responde «cómo está ahora»; el historial responde «qué ocurrió». Ninguno debe utilizarse como sustituto automático del otro.

Registra también quién puede provocar una transición y si existen efectos asociados: generar una notificación, actualizar un resumen o habilitar un siguiente proceso. Estos efectos deben estar localizables, aunque se ejecuten fuera del motor.

Documentar vistas, rutinas, disparadores e índices por su propósito

El modelo no termina en las tablas. Una base puede contener lógica que transforma resultados, genera valores o modifica datos como consecuencia de otras operaciones. Si esa lógica queda fuera de la documentación, el mantenimiento puede producir efectos inesperados.

Vistas como contratos de lectura

Una vista de intervenciones cerradas debería indicar qué estados incluye, qué fecha utiliza para agrupar, cómo trata importes pendientes y qué unidad representa cada fila. Es importante registrar si muestra datos actuales o un resumen actualizado mediante un proceso aparte.

No copies la definición SQL a varios documentos. Conserva la definición versionada y añade una explicación de las decisiones que no son evidentes leyendo el código. El consumidor necesita conocer el contrato, no necesariamente todos los detalles de implementación.

Rutinas y disparadores

Para cada componente importante documenta entradas, salidas, tablas afectadas, efectos secundarios, contexto de permisos y comportamiento ante errores. En un disparador, registra además el evento que lo activa y si actúa por fila o por sentencia cuando esa distinción exista en el motor.

Una actualización aparentemente local puede generar historial, recalcular datos o invocar otra lógica. La documentación debe mostrar esas consecuencias. No basta con describir el procedimiento que una persona ejecuta manualmente si existen automatismos adicionales.

Índices con una razón conservable

El inventario técnico puede mostrar columnas y método de un índice. La explicación mantenible debe añadir por qué existe: apoyar una búsqueda, garantizar una unicidad o responder a un patrón concreto. Un índice de integridad no debe evaluarse únicamente por estadísticas de uso de consultas.

La documentación conserva propósito y dependencia. La decisión de crear, cambiar o retirar índices requiere el análisis específico de rendimiento, que se desarrolla en el diagnóstico de una base de datos lenta.

Registrar origen, transformaciones y consumidores del dato

Conocer dónde se guarda un dato no explica cómo llega ni quién depende de él. La documentación debe seguir los flujos importantes: origen, validación, transformación, destino y consumidores.

En el ejemplo, una solicitud puede registrarse manualmente o llegar mediante una integración. Debe quedar claro qué identificador evita duplicados, qué fecha procede del origen y cómo se distingue un reintento de una nueva solicitud. De lo contrario, un mantenimiento aparentemente inocuo puede romper la reconciliación.

Flujo ficticio: recepción de solicitudes externas
Origen: sistema de asistencia del colaborador
Identidad del evento: origen + referencia externa
Destino: intervención de la aplicación interna
Transformaciones: equivalencia de estados y formato de fechas
Autoridad: el origen define la solicitud; el sistema interno su ejecución
Errores: quedan separados de las solicitudes aceptadas
Consumidores: planificación, seguimiento e informe de cierre

Esta ficha describe decisiones; los detalles de transporte, autenticación y reintentos pertenecen al procedimiento de integración. La documentación del modelo debe enlazarlo y conservar las reglas que afectan al significado de los datos.

Dependencias fuera del motor

Una hoja de cálculo, una exportación periódica o un script pueden consultar una columna sin dejar una dependencia formal en el catálogo de la base. Por eso hay que incorporar consumidores identificados en aplicaciones, tareas y procesos de negocio.

La explicación completa de los mecanismos de intercambio se encuentra en cómo integrar varias bases de datos. Aquí interesa que una persona que vaya a cambiar un objeto pueda localizar quién escribe y quién lee ese objeto.

Extraer la estructura real sin confundirla con documentación completa

La estructura técnica conviene obtenerla del sistema, no transcribirla manualmente. El motor conoce nombres, tipos, restricciones y otros atributos que pueden exportarse y compararse. Esa extracción reduce errores de copia y ayuda a detectar diferencias entre entornos.

El estándar SQL define information_schema, que proporciona vistas de metadatos en motores que lo implementan. PostgreSQL advierte que las características específicas del producto pueden requerir sus catálogos propios; véase su documentación del esquema de información.

Una consulta de inventario, no un exportador universal

El siguiente ejemplo de consulta para PostgreSQL 17 obtiene información visible de columnas del esquema ficticio servicio. No modifica datos de negocio:

SELECT
    table_schema,
    table_name,
    ordinal_position,
    column_name,
    data_type,
    character_maximum_length,
    numeric_precision,
    numeric_scale,
    is_nullable,
    column_default
FROM information_schema.columns
WHERE table_schema = 'servicio'
ORDER BY table_name, ordinal_position;

La vista muestra columnas accesibles a la identidad que consulta. Un resultado vacío puede deberse al entorno, al esquema o a los permisos; no demuestra por sí solo que no existan objetos. La cobertura se especifica en la referencia de information_schema.columns.

Esta consulta tampoco reconstruye toda la base: no describe por sí sola claves foráneas, índices, disparadores, políticas de acceso ni semántica de negocio. Debe formar parte de un conjunto de extracciones cuyo alcance esté documentado.

Registrar cómo se obtuvo el inventario

Conserva el motor, el entorno, la fecha, la identidad o nivel de visibilidad utilizado y la herramienta de extracción. Una comparación entre dos inventarios solo es fiable si sus diferencias no proceden de una cobertura distinta.

Las cantidades de filas y tamaños pueden quedar como datos de referencia fechados o enlaces a monitorización. No necesitan convertirse en cifras manuales supuestamente actuales dentro de cada ficha.

Usar comentarios técnicos sin almacenar secretos

Los comentarios del esquema permiten acercar parte del significado a los objetos que lo necesitan. Son adecuados para definiciones breves, unidades, distinciones entre nulo y cero o referencias a una regla más extensa.

Por ejemplo, esta sentencia de PostgreSQL modifica el comentario de una columna ya existente. Es un cambio de metadatos: debe realizarse con autorización y preferiblemente incorporarse a la migración correspondiente, no ejecutarse de forma improvisada en producción.

COMMENT ON COLUMN servicio.intervenciones.importe_acordado IS
'Importe acordado en EUR, sin impuestos. NULL: pendiente de acordar. 0: servicio sin cargo adicional.';

Los comentarios no son un almacén privado. PostgreSQL indica que los usuarios conectados pueden ver los comentarios de objetos de la base, por lo que no deben contener información crítica de seguridad. Esta advertencia figura en la documentación de COMMENT.

Evita contraseñas, cadenas de conexión con secretos, datos personales de ejemplo y detalles sensibles que no correspondan a ese nivel de visibilidad. Una definición de campo debe poder consultarse sin exponer credenciales.

Los comentarios tampoco sustituyen decisiones de arquitectura, flujos o procedimientos complejos. Su función es aportar una explicación próxima al objeto y, cuando proceda, una referencia al documento más amplio.

Preparar un análisis de impacto antes de cambiar un objeto

Un cambio necesita identificar qué depende del objeto y qué significado puede alterar. Esa evaluación debe combinar dependencias que conoce el motor y relaciones que existen fuera de él.

PostgreSQL registra dependencias entre diversos objetos, pero su documentación explica límites, por ejemplo cuando ciertas referencias están dentro del cuerpo de funciones definido como texto. No debes interpretar «el motor permite el cambio» como «ningún consumidor se verá afectado». La referencia es el seguimiento de dependencias de PostgreSQL.

Una ficha de impacto breve

Para un campo importante, conserva los consumidores conocidos y el criterio de compatibilidad: aplicación que escribe, consultas que leen, exportaciones, índices, restricciones y procesos de transformación. No hace falta duplicar todo el código; necesitas saber dónde localizarlo y quién puede validar el cambio.

También distingue cambios de nombre, de formato, de presencia y de significado. Cambiar un decimal por otro decimal puede mantener el tipo y alterar completamente su interpretación si se pasa de euros a céntimos. Una comparación de esquema por sí sola no detectaría esa ruptura semántica.

No utilizar operaciones destructivas como herramienta de exploración

El análisis de impacto debe apoyarse en catálogos, código, registros y pruebas controladas. No ejecutes borrados o cambios destructivos en producción para «ver qué falla». Una dependencia externa puede descubrirse demasiado tarde, y no todo cambio es reversible con una operación sencilla.

Caso práctico: hacer obligatorio un dato sin cambiar su significado

En la aplicación ficticia, la dirección pide que las intervenciones cerradas tengan un importe acordado. Una solución precipitada sería sustituir los nulos por cero y convertir toda la columna en obligatoria. La documentación permite ver por qué eso no responde a la necesidad.

Definir la regla exacta

La necesidad no es «ninguna intervención puede tener importe nulo», sino «una intervención no puede quedar cerrada sin que se conozca su importe». La solicitud abierta puede seguir pendiente y el servicio sin cargo debe conservar el cero como cantidad real.

La nueva documentación debe identificar las reglas anteriores, las nuevas y los registros históricos que necesitan revisión. No debe afirmar retrospectivamente que todos los cierres antiguos cumplieron una validación que entonces no existía.

Localizar escritores y lectores

Revisa el formulario de cierre, las integraciones, las importaciones y los procesos que generan informes. Una API puede seguir cerrando intervenciones sin importe aunque la pantalla principal ya lo exija. También puede haber informes que interpreten todos los nulos como casos abiertos.

Preparar pruebas de significado

El caso 101 debe seguir siendo válido mientras permanezca abierto. Intentar cerrarlo sin importe debe rechazarse conforme a la nueva regla. Los casos 102 y 103 deben conservar sus significados. Una intervención cancelada requiere el tratamiento que la política defina, no el que resulte accidentalmente de reutilizar la lógica de cierre.

Esta forma de documentar transforma una petición ambigua en una modificación verificable. Los scripts se preparan después; primero se aclara qué comportamiento se pretende mantener y cuál debe cambiar.

Versionar documentación, esquema y migraciones de forma coordinada

La documentación debe poder relacionarse con una versión concreta del modelo. No significa duplicar todos los documentos para cada cambio, sino conservar un historial y una referencia que permita reconstruir qué descripción correspondía al estado revisado.

Una organización sencilla podría utilizar:

asistencia/
  README.md
  modelo/
    tablas.md
    relaciones.md
    reglas-negocio.md
    flujos.md
  diccionario/
    intervenciones.md
    actuaciones.md
  referencias/
    operaciones-servidor.md
    accesos.md
  migraciones/
    024-regla-importe-cierre.sql
  decisiones/
    importe-pendiente-y-servicio-sin-cargo.md

Los nombres son un ejemplo; puedes emplear una wiki u otra herramienta. Lo importante es separar definiciones vigentes, scripts reproducibles y decisiones históricas. El archivo de migración no sustituye a la explicación funcional del cambio.

Actualizar como parte del trabajo, no cuando sobre tiempo

Una modificación que afecta al significado de un campo debe actualizar su ficha, sus pruebas y sus consumidores documentados. Cuando se añade una relación, debe reflejarse su cardinalidad y su mecanismo de garantía. Cuando se retira una interfaz, debe señalarse su sustitución.

La diferencia entre entornos también debe quedar visible. La documentación puede describir una migración aprobada que todavía no se ha desplegado en producción. Registra ese estado para evitar que un administrador confunda el diseño futuro con la situación que debe mantener hoy.

El proceso de promoción entre entornos se desarrolla en la organización de desarrollo, pruebas y producción. El documento del modelo aporta el significado y la compatibilidad que ese proceso debe preservar.

Qué puede automatizarse y qué necesita validación humana

Una herramienta puede extraer nombres, tipos, definiciones y algunas relaciones. También puede generar diagramas y detectar diferencias de estructura. Eso reduce trabajo repetitivo, pero no revela automáticamente todas las reglas del negocio.

El significado de un importe, la razón de una redundancia histórica o el uso de una columna en una hoja de cálculo externa requieren contexto. Presentar una descripción generada a partir del nombre como una definición confirmada puede introducir errores más convincentes que un campo sin documentar.

Marcar el origen de cada afirmación

Conviene distinguir información extraída del motor, interpretación validada por una persona y cuestión pendiente. Por ejemplo: «Nulabilidad extraída del esquema», «Significado del nulo confirmado por operaciones» y «Consumidor externo pendiente de localizar».

La incertidumbre explícita es útil. Una definición falsa puede propagarse a consultas e informes; una duda señalada permite decidir dónde investigar antes de cambiar.

Detectar documentación desactualizada

Una comprobación automática puede advertir que hay columnas nuevas sin ficha, tablas retiradas que siguen documentadas o diferencias entre un inventario y el estado vigente. Otra revisión puede buscar reglas sin prueba o documentos sin responsable.

Estas comprobaciones mejoran cobertura, pero no certifican significado. Un campo puede seguir existiendo con el mismo nombre y haber cambiado de uso. La revisión técnica y la funcional deben complementarse.

Incluir clasificación y ciclo del dato sin duplicar otras políticas

La documentación del modelo debe indicar qué campos son sensibles, qué interfaces exponen información y qué datos son reproducibles. No debe contener valores reales innecesarios ni convertirse en una exportación de la base.

Utiliza ejemplos sintéticos. En una ficha basta con mostrar un identificador inventado, un estado o un importe didáctico. Las capturas deben revisarse para que no revelen clientes, credenciales o detalles que no aportan valor a la explicación.

Quién puede consultar la propia documentación

El detalle del modelo puede ser información interna. Define una visibilidad proporcionada: una explicación general para usuarios, fichas técnicas para mantenimiento y referencias restringidas para aspectos sensibles. La documentación pública de una API no tiene por qué revelar toda la estructura interna.

Historificación, archivo y retirada

Registra qué representa el histórico y dónde se define su conservación. Distingue borrar físicamente, marcar como inactivo y archivar: no tienen el mismo efecto sobre relaciones, consultas y recuperación. No inventes plazos de conservación a partir del tamaño de una tabla.

La estrategia puede ampliarse con la gestión de históricos sin perder trazabilidad. La ficha de la base debe conservar las reglas que afectan a su modelo y enlazar las políticas correspondientes.

Comprobar si la documentación sirve para mantener la base

La prueba más útil consiste en realizar una tarea de comprensión sin recurrir a quien diseñó el sistema. El objetivo no es modificar producción, sino verificar que la información necesaria puede localizarse y que no se contradice.

Propón, por ejemplo, estas preguntas: ¿cómo se identifica una intervención?, ¿puede existir sin equipo?, ¿qué significa un importe nulo?, ¿qué conserva el historial después de reabrir?, ¿quién consume el informe de cierres? Si las respuestas obligan a adivinar, has localizado trabajo documental de alto valor.

Cobertura antes que volumen

Una revisión inicial puede centrarse en las tablas críticas y en las reglas que afectan a información irreversible. Después se amplía a objetos auxiliares. Esta priorización permite empezar a obtener utilidad sin esperar a documentar cada tabla secundaria.

La documentación debería permitir localizar la versión del modelo, definir la granularidad de las tablas principales, explicar campos ambiguos, identificar relaciones implementadas y encontrar consumidores conocidos. También debería señalar las lagunas pendientes en lugar de transmitir una falsa exhaustividad.

Un criterio de finalización para cada cambio

Considera una modificación terminada cuando su estructura, significado, reglas y pruebas han quedado coherentes. Si cambia un objeto pero nadie actualiza la definición utilizada por los informes, la implementación técnica puede estar desplegada y el mantenimiento seguir incompleto.

Con esta disciplina, la documentación deja de ser una tarea separada que siempre se pospone. Pasa a ser parte de conservar la base en un estado comprensible.

Preguntas frecuentes

Conclusión

Documentar una base de datos para facilitar su mantenimiento consiste en conservar la relación entre estructura y significado. El motor puede mostrar tipos y restricciones; el documento debe explicar qué representa cada fila, cómo se interpreta cada valor y qué decisiones justifican el comportamiento.

Una ficha de entrada, un inventario por granularidad, un diccionario preciso y un mapa de relaciones y consumidores proporcionan una base sólida. Las reglas deben indicar dónde se aplican, las dependencias deben incluir lo que queda fuera del motor y los cambios deben relacionarse con versiones y pruebas.

La documentación útil no intenta parecer completa ocultando dudas. Identifica lo conocido, deja visibles las incertidumbres y permite evaluar una modificación sin inventar el significado del dato. Esa capacidad reduce la dependencia de la memoria y hace que una base siga siendo mantenible cuando cambian las aplicaciones y las personas.