Standards and Guides

Standards define the rules the team must follow when producing and managing information: naming conventions, file formats, modeling requirements, coordinate systems, and so on. Guides are complementary documents that explain how to apply those rules in practice, such as step-by-step procedures for a specific software or activity.

Defining standards and guides in the BEP gives the whole team a single, authoritative reference for how work should be done, reducing ambiguity and rework.

Adding a standard

If you have a standard already written or can describe its content:

Please add a standard to the BEP called [standard name]. It covers the following: [description of what the standard defines].

If the standard is a document that already exists and you want to attach it:

Please add a standard called [standard name] and attach the following file as its content: [attach or paste the document].

Referencing BEP data from a standard

One of the most useful things about a standard in dotBEP is that its prose is not static text. It can point directly at data that lives elsewhere in the BEP, a team’s name, another standard, a value defined as reference data, instead of repeating it as plain text. That reference resolves fresh every time the standard is read, so it never drifts out of sync with the entity it points to.

In the [standard name] standard, reference the [team name] team's name instead of writing it out.

In the [standard name] standard, embed a live table of the [reference data domain name] domain, so readers always see the current values.

In the [standard name] standard, embed a live table of the project's disciplines, teams, or naming convention.

This keeps the standard’s content and the BEP’s own entities in sync: if a team is renamed later, the reference updates with it, and dotBEP will not let you delete a team, member, or other entity that a standard still depends on.

Under the hood, this works through two related but distinct pieces of syntax. A single value, like a team’s name, is a {{<JSONata expression>}} wrapped inline in the standard’s prose. A full table, like a reference data domain or the list of disciplines, is a :::bep:{entity}::: block on its own line. You do not need to write either yourself, describing what you want to the AI is enough, but if you want the full reference, see dotBEP Flavored Markdown.

If you mention an entity, reference it

Whenever a standard’s prose names something that already exists as an entity in the BEP, a piece of software, a team, a discipline, another standard, reference it inline instead of typing its name as plain text, even for a single passing mention.

Instead of writing "Autodesk Forma" as plain text in the [standard name] standard, reference that software's name.

The reason is the same as for any other reference: a plain-text mention can drift out of sync with the entity it names, if that software is renamed or replaced later, nothing catches the mismatch. A reference resolves the current name every time the standard is read, so it is never wrong, and dotBEP will not let the entity be deleted while a standard still depends on it.

If what you want to mention does not exist as an entity yet, a tool the project actually uses but that was never added to the BEP’s software list, for example, that is usually a sign it is worth adding, rather than a reason to fall back to plain text.

Structured data belongs in reference data, not prose

When a standard needs to define an allowed set of values, a required field list, a folder structure, or any other structured data, define it as reference data rather than describing it in prose, then reference it or embed it as a table in the standard as shown above.

Instead of writing out the CDE folder structure as text, define it as a reference data domain and embed it as a table in the [standard name] standard.

Prose can be read by a person, but not consumed by anything else with certainty. A defined reference data domain is written once and can be reused by whatever needs it: a workflow that automatically checks a project’s actual CDE folder structure against what the standard requires, an automation that verifies whether an RFI carries every field the BEP demands, or any other check that needs to read defined values with certainty instead of parsing text meant for a person. Prose that only describes structured data, “the folder structure is: WIP, Shared, Published, Archive”, exists solely for a reader; nothing else in the BEP can act on it. Defining it as reference data keeps it just as readable while also making it usable by workflows and future integrations.

Adding a guide

In dotBEP, guides are not written documents. A guide is a curated collection of annexes: external references such as documents, links, or videos that explain how to carry out a specific activity. Guides are typically linked to workflow actions, so that when a team member is executing a step in a workflow, they have direct access to the references that explain how to do it.

To add a guide and its annexes:

Please add a guide called [guide name] with the following annexes: [annex name] ([url or description]), [annex name] ([url or description]).

To link a guide to a specific workflow action:

Link the [guide name] guide to the [step name] step in the [workflow name] workflow.

Reviewing what is already defined

Before adding more standards or guides, it is useful to see what is already in the BEP:

List the standards and guides currently defined in the BEP.