Estándares y guías

Los estándares definen las reglas que el equipo debe seguir al producir y gestionar información: convenciones de nomenclatura, formatos de archivo, requisitos de modelado, sistemas de coordenadas, etc. Las guías son documentos complementarios que explican cómo aplicar esas reglas en la práctica, como procedimientos paso a paso para un software o actividad específica.

Definir estándares y guías en el BEP le da a todo el equipo una referencia única y autorizada de cómo debe hacerse el trabajo, reduciendo la ambigüedad y el retrabajo.

Añadir un estándar

Si tienes un estándar ya redactado o puedes describir su contenido:

Por favor, añade un estándar al BEP llamado [nombre del estándar]. Cubre lo siguiente: [descripción de lo que define el estándar].

Si el estándar es un documento que ya existe y quieres adjuntarlo:

Por favor, añade un estándar llamado [nombre del estándar] y adjunta el siguiente archivo como su contenido: [adjunta o pega el documento].

Referenciar datos del BEP desde un estándar

Una de las cosas más útiles de un estándar en dotBEP es que su prosa no es texto estático. Puede apuntar directamente a datos que viven en otra parte del BEP, el nombre de un equipo, otro estándar, un valor definido como dato de referencia, en vez de repetirlo como texto plano. Esa referencia se resuelve de nuevo cada vez que se lee el estándar, así que nunca se desincroniza de la entidad a la que apunta.

En el estándar [nombre del estándar], referencia el nombre del equipo [nombre del equipo] en vez de escribirlo directamente.

En el estándar [nombre del estándar], incrusta una tabla en vivo del dominio de datos de referencia [nombre del dominio], para que los lectores siempre vean los valores actuales.

En el estándar [nombre del estándar], incrusta una tabla en vivo de las disciplinas, los equipos o la convención de nomenclatura del proyecto.

Esto mantiene sincronizado el contenido del estándar con las entidades propias del BEP: si un equipo se renombra después, la referencia se actualiza con él, y dotBEP no te dejará eliminar un equipo, miembro u otra entidad de la que un estándar todavía dependa.

Por debajo, esto funciona mediante dos sintaxis relacionadas pero distintas. Un solo valor, como el nombre de un equipo, es una {{<expresión JSONata>}} envuelta en línea dentro de la prosa del estándar. Una tabla completa, como un dominio de datos de referencia o la lista de disciplinas, es un bloque :::bep:{entidad}::: en su propia línea. No necesitas escribir ninguna de las dos tú mismo, con describirle a la IA lo que quieres basta, pero si quieres la referencia completa, consulta dotBEP Flavored Markdown.

Si mencionas una entidad, referénciala

Cada vez que la prosa de un estándar nombre algo que ya existe como entidad en el BEP, un software, un equipo, una disciplina, otro estándar, referéncialo en línea en vez de escribir su nombre como texto plano, incluso para una sola mención puntual.

En vez de escribir "Autodesk Forma" como texto plano en el estándar [nombre del estándar], referencia el nombre de ese software.

El motivo es el mismo que para cualquier otra referencia: una mención en texto plano puede desincronizarse de la entidad que nombra, si ese software se renombra o se reemplaza después, nada detecta el desajuste. Una referencia resuelve el nombre actual cada vez que se lee el estándar, así que nunca queda desactualizada, y dotBEP no dejará eliminar la entidad mientras un estándar todavía dependa de ella.

Si lo que quieres mencionar todavía no existe como entidad, una herramienta que el proyecto realmente usa pero que nunca se añadió a la lista de software del BEP, por ejemplo, eso suele ser una señal de que vale la pena añadirla, en vez de una razón para recurrir al texto plano.

Los datos estructurados van en datos de referencia, no en prosa

Cuando un estándar necesita definir un conjunto de valores permitidos, una lista de campos requeridos, una estructura de carpetas, o cualquier otro dato estructurado, defínelo como dato de referencia en vez de describirlo en prosa, y luego referéncialo o incrústalo como tabla en el estándar como se mostró arriba.

En vez de escribir la estructura de carpetas del CDE como texto, defínela como un dominio de datos de referencia e incrústala como tabla en el estándar [nombre del estándar].

La prosa puede leerla una persona, pero no la puede consumir con certeza ninguna otra cosa. Un dominio de datos de referencia se define una sola vez y puede ser reutilizado por lo que sea que lo necesite: un flujo de trabajo que verifica automáticamente la estructura de carpetas del CDE de un proyecto contra lo que exige el estándar, una automatización que valida si un RFI trae todos los campos que exige el BEP, o cualquier otra verificación que necesite leer valores definidos con certeza en vez de interpretar texto pensado para una persona. Una prosa que solo describe datos estructurados, “la estructura de carpetas es: WIP, Shared, Published, Archive”, existe únicamente para quien la lee; nada más en el BEP puede actuar sobre ella. Definirla como dato de referencia la mantiene igual de legible mientras la hace utilizable por flujos de trabajo e integraciones futuras.

Añadir una guía

En dotBEP, las guías no son documentos escritos. Una guía es una colección curada de anexos: referencias externas como documentos, enlaces o videos que explican cómo llevar a cabo una actividad específica. Las guías suelen vincularse a las acciones de los flujos de trabajo, de modo que cuando un miembro del equipo está ejecutando un paso, tiene acceso directo a las referencias que explican cómo hacerlo.

Para añadir una guía y sus anexos:

Por favor, añade una guía llamada [nombre de la guía] con los siguientes anexos: [nombre del anexo] ([url o descripción]), [nombre del anexo] ([url o descripción]).

Para vincular una guía a una acción específica de un flujo:

Vincula la guía [nombre de la guía] al paso [nombre del paso] en el flujo [nombre del flujo].

Revisar lo que ya está definido

Antes de añadir más estándares o guías, es útil ver qué ya hay en el BEP:

Lista los estándares y guías actualmente definidos en el BEP.