At the 2015 S1000D User Forum, information was provided about the new
brDoc, coming to Issue 4.2. One of the
audience member asked what is the difference between
and the BREX. I thought the answer the presenter gave was not very
clear. I do not recall specifically what the presenter said, but I
could tell the audience member was still confused.
During a break, I approached the audience member and said something like the following:
brDocexplains the "Why" of your business rules while the BREX provides the "How".
The BREX DM mainly lists out the rules your data was authored
against, but may not provide the reasoning behind the decisions made
in establishing the rule. For example, you may have a BREX rule
stating, "All procedural steps must have an authored ID," which
can be codified in a
brDoc DM would provide the reasons the rule exists,
which may be due to cross-referencing requirements for the project.
In Issue 4.2, the BREX schema has been updated so for a given rule,
you can reference back to the
brDoc data module that provides
reasoning behind the rule. This linking is done with
BR decision identifiers, which are specified in the
brDoc data module via
In the BREX, you reference the identifiers via
For example, in the
brDoc DM, you may have something
like the following:
... <brDecision brDecisionIdentNumber="MYPROJ-BRD-00001"> ... <brDecisionExplanation> <para>Identifiers on procedural steps are required so specific steps can easily be identified in the viewing system when the maintainer submits a problem report on a procedure and/or specific steps of a procedure. </para> </brDecisionExplanation> </brDecision> ...
And in your BREX, you have something like the following to refer
back to the decision documented in the
brDoc data module:
... <structureObjectRule...> <brDecisionref brDecisionIdentNumber="MYPROJ-BRD-00001"/> <objectPath allowedObjectFlag="0">//proceduralStep[not(@id)]</objectPath> <objectUse>All procedural steps must have an authored ID.</objectUse> </structureObjectRule> ...