brDoc Schema: What does brRelatedTo stand for?

In this post, our Business Rules (BR) trainer Victoria Ichizli-Bartels will explain what the element brRelatedTo — standing for BR decision point relationship – means in the new business rule document (brDoc) Schema introduced in the S1000D Issue 4.2.

As in prior two posts in this series, a note beforehand: for the simplicity and readability purposes I omitted the “<” and “>” brackets at the element names.

Before we discuss today’s topic, let us recall what we need to record a business rules decision point (BRDP) and all the information related to it including the decisions made. We need to use the brPara (business rules paragraph) construct with the following structure :

brPara:

  • brRelatedTo
  • brDecisionPointContent
  • brDecision
  • brAudit

Business Rules Decision Points (BRDP) count 552 in the S1000D Issue 4.1 and 427 in Issue 4.2. There were more than 700 BRDP in the Issue 4.0.1, where these were defined for the first time more or less distinctly. The reduction of the BRDP number from Issue to Issue goes with the cleanup and tidying of the specification’s content.

The obvious question raising, when you see the sheer number of the decision points to address is how they relate to each other. Is there a way to group, or map them into a logical mind map with some of the decision points being in the center of those clusters or groups?

Business Rules Working Group (BRWG) had several attempts at this task. And it appeared both cumbersome and hugely dependent on the content of a particular project.

At some point during the struggle with that task, we, the BRWG members, asked ourselves whether there were other, more distinct and recognizable relationships of the BRDP? Did they relate to something else more clearly?

And as we started looking closer, we discovered that they indeed did.

First of all, there was the specification text. The intention was from the very beginning of the business rules standardization — and especially in Issue 4.1 where each BRDP got a unique number — to define the business rules decision points only once in the S1000D text. There might have been redundant BRDP in previous Issues, and there are a few still in Issue 4.2, but the intention always was to define each BRDP once. So there is a straightforward relation there. For example, BRDP-S1-00021 on the use of ASD-STE100® is defined in Chap 3.9.1, Para 2.1 and BRDP-S1-00164 on the units of measure to be used is given in Chap 3.9.5.2.1.10, Para 2.1.4.1.

The next step was to identify, which BRDP belong to which business rules category. This exercise was not an obvious one, and the same BRDP can belong to several categories. For example, the BRDP-S1-00053 concerning the data module changed/revised ratio can be attributed to both BR category 5 “Business process business rules” and BR category 8 “Data integrity and management business rules.”

Some of the chapters of the specification are dedicated to particular Schemas, such as  Chap 3.9.5.2.14. It is detailing the maintenance checklists and inspections Schema. Some Schemas are addressed only in portions of some of the chapters, such as Data Dispatch Note in Chap 7.5.1, Para 2.3.1. Other require more than one chapter to accommodate a Schema’s description. An example here is Chap 3.9.5.2.11 and all its 14 sub-chapters to describe the Common Information Repository Schema. So, we decided to map the BRDP also to S1000D XML Schemas. We detected once again that one BRDP could relate to more than one Schema. That is especially true for the BRDP on the coding of the CSDB objects.

The last mapping to configurable attributes came naturally since some of those attributes relate to individual Schemas.

If you look at the structure of the element brRelatedTo, you will discover that it reflects the mappings mentioned above:

  • The element sourceDocRef is standing for the business rules document reference. It can be the S1000D specification text or the project/organization’s documentation if the BRDP is the project or organization specific.
  • The element brCategoryGroup is standing for the business rule category group and mapping the given BRDP to all relevant BR categories.
  • The element s1000dSchemas lists the S1000D Schemas, to which the given BRDP relates to.
  • The element configAttributes illustrating the BRDP relation to configurable attributes.

Besides, there is the element remarks, a common construct, which can be used for a project to record notes, for example, on how the given BRDP relates in their opinion to other BRDP, or other remarks requiring special attention when dealing with it.

View all bitesize business rules

Looking to learn more about Business Rules in the world of S1000D?

Book your place on our S1000D Business Rules training course delivered by Victoria Ichizli-Bartels.

This course is for anyone who needs an understanding of the principles of S1000D prior to implementing the standard.  It covers the technical and business aspects of Business Rules and how to implement it and its implications for technical publications. Find out more.

About Victoria Ichizli-Bartels

Victoria has been working with S1000D since 2004, first for German Defence, then for a major S1000D software vendor and today as part of her own business. In the S1000D community, Victoria serves as the Business Rules Working Group (BRWG) chair since 2005.

To book your place call +44 (0)20 8722 8400 or email moc.n1537650104okem@1537650104greb.1537650104ennas1537650104us1537650104