Monday, November 9, 2015

What is the difference between brDoc and BREX?

At the 2015 S1000D User Forum, information was provided about the new schema type, brDoc, coming to Issue 4.2. One of the audience member asked what is the difference between brDoc 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:

brDoc explains 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 <structureObjectRule>. The 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 <brDecision> nodes. In the BREX, you reference the identifiers via <brDecisionRef> nodes.

For example, in the brDoc DM, you may have something like the following:

  <brDecision brDecisionIdentNumber="MYPROJ-BRD-00001">
      <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>

And in your BREX, you have something like the following to refer back to the decision documented in the brDoc data module:

    <brDecisionref brDecisionIdentNumber="MYPROJ-BRD-00001"/>
    <objectPath allowedObjectFlag="0">//proceduralStep[not(@id)]</objectPath>
    <objectUse>All procedural steps must have an authored ID.</objectUse>

No comments:

Post a Comment