Datos de referencia

Parte de lo que un proyecto necesita documentar no es prosa, sino pequeños hechos estructurados: una enumeración de estados con sus colores asociados, una estructura de carpetas de CDE, el conjunto de campos de metadata requeridos por archivo. Los datos de referencia son la forma en que dotBEP almacena ese tipo de información: estructurada, organizada en dominios con nombre, y definida una sola vez a nivel del BEP en vez de duplicarse dentro de un documento en particular.

Piensa en la relación entre datos de referencia y estándares así: un estándar es la narrativa, escrita para personas, que explica una regla o un requisito. Los datos de referencia son la versión estructurada de los valores específicos detrás de esa narrativa, escrita para leerse con certeza por lo que sea que la consuma, un script, una integración, otra parte del BEP, sin necesidad de interpretar prosa para adivinarlos.

Dos formas de usar datos de referencia

Configurar sistemas externos

El caso de uso principal de los datos de referencia es el consumo externo. Una integración, un script, o cualquier herramienta conectada a tu proyecto puede leer un dominio de datos de referencia y obtener de vuelta los valores actuales exactos que necesita, un conjunto de estados permitidos, una estructura de carpetas, una lista de campos requeridos, con certeza.

Crea un dominio de datos de referencia llamado "CDE" para las convenciones de nuestro Entorno Común de Datos, con la estructura de carpetas y los campos de metadata requeridos por archivo.

Referenciarlo desde un estándar

Los datos de referencia también pueden referenciarse directamente desde la prosa de un estándar, para que el estándar siempre muestre los valores actuales en vez de una copia que puede desincronizarse en silencio. Ver Estándares y guías para cómo referenciar datos de referencia, o incrustar una tabla en vivo, desde un estándar.

Dominios y nodos

Un dominio agrupa datos relacionados bajo un nombre, por ejemplo “Topics” para cómo se clasifican las incidencias de coordinación, o “CDE” para las convenciones de tu Entorno Común de Datos. Dentro de un dominio, cada entrada es un nodo: una pequeña pieza de datos estructurados que puede tener sus propios atributos y, opcionalmente, hijos, así puedes representar tanto listas planas (un conjunto de estados) como jerarquías (una estructura de carpetas).

Añade un dominio de datos de referencia "Topics" con un grupo "Status" que contenga "Open", "In progress" y "Resolved", cada uno con un label y un color.

En el dominio "CDE", añade un grupo "Folders" con "WIP" conteniendo "Structural", "MEP" y "Architecture" como subcarpetas, y "Shared", "Published" y "Archive" como carpetas de primer nivel.

Key y label

Cada nodo tiene tanto un key como un label, y ambos cumplen propósitos distintos.

El key es el identificador técnico: es lo que otro software lee para trabajar con el nodo de forma confiable, y no necesita ser legible para una persona. El label es obligatorio, y es lo que realmente debe mostrarse a alguien que lea el dominio.

Si un key técnico específico importa, por ejemplo porque una integración ya existente espera un valor particular, dilo explícitamente. Si no, describe los valores que quieres en lenguaje natural y deja que la IA elija un key razonable.

Agrupar datos de la misma forma

Al definir un dominio, mantén los datos que comparten la misma forma bajo su propio nodo, en vez de mezclar tipos de datos distintos en el mismo nivel. Un dominio de CDE, por ejemplo, es más claro como dos grupos separados, uno para la estructura de carpetas y otro para los campos de metadata requeridos, que como una sola lista plana mezclando ambos. Esto mantiene cada parte del dominio predecible para quien sea que lo lea, ya sea una persona, un sistema externo, o una tabla incrustada en un estándar.

Referenciar otros datos del BEP

Los atributos de un nodo pueden apuntar directamente a otros datos del BEP en vez de repetirlos como texto plano, igual que puede hacerlo un estándar. Si una carpeta de tu dominio CDE pertenece a un equipo específico, referencia el nombre de ese equipo en vez de escribirlo directamente:

En el dominio "CDE", establece el owner de la carpeta "Structural" bajo "WIP" como el equipo [nombre del equipo], referenciado por su nombre.

Si el equipo se renombra después, la referencia se actualiza automáticamente, y dotBEP no te dejará eliminar un equipo, miembro u otra entidad de la que los datos de referencia todavía dependan.