brDoc Schema: What is a Business Rules Paragraph (brPara)?

In this post, our Business Rules trainer Victoria Ichizli-Bartels will explain the brPara (business rules paragraph) and the reasons behind creating such a structure inside the new brDoc (business rules document) Schema in the S1000D Issue 4.2.

A note beforehand: for the simplicity and readability purposes I omitted the “<” and “>” brackets at the element names.

In the last post, titled “Understanding the Business Rules Document (brDoc) Schema” we discussed why the creation of the brDoc Schema was necessary.

One of the reasons mentioned was the nature of many business rules documents having a flowing text format, such as Authors’ Guidance Documents.

That is why the Business Rules Working Group (BRWG) took the descriptive Schema as the basis for the brDoc Schema. Ninety or even more percent of the brDoc Schema is equivalent to the descriptive Schema.

If we imagine the well-known descriptive content out of the brDoc Schema, then the main structure of the Schema becomes extremely simple:

  • brDoc:
    • brLevelledPara:
      • brDecision
      • brPara:
        • brRelatedTo
        • brDecisionPointContent
        • brDecision
        • brAudit

The repeatable element brLevelledPara is the one that is to ninety percent or rather more equal to the levelledPara inside the descriptive Schema. The brDecision and brPara, as well as the lack of alternates, mark the only differences between the two.

And since the brDecision is also a part of brPara it makes sense to take a look first at the brPara, i.e., business rules paragraph.

If you have ever defined business rules decisions for an S1000D project, then the first thing you did, you addressed, either a list of, or one-by-one, the business rules decision points (BRDP).

The initial impulse we (the BRWG) had while developing the Schema was to position a BRDP with its content first, then let it be followed by a decision taken, including its content, and then all the details concerning deadlines, actions related to decision making for that decision point, etc. But then we realized that there might be more than one decision per decision point and that, if decisions are taken, you could never consider a decision point without the corresponding decisions, and vice versa. So we had to create a self-contained structure to embrace and to document all that. We created a business rules paragraph. A paragraph, because it is usually a piece of text and since it has a specific nature, it got its business rules touch to it.

As soon as we created the structure, or shortly after, we realized that the unique identifier of a decision point, which for the BRDP defined by the S1000D since the Issue 4.1 start with the prefix “BRDP-S1-”,  should be not on the BRDP content (brDecisionPointContent) but on the BR paragraph (brPara). The reason for this is that when referring to a BRDP, you automatically refer also to all the decisions taken upon it, if any were made, or to a placeholder if none was made yet.

Here is the simplified structure of the brPara again:

  • brPara:
    • brRelatedTo
    • brDecisionPointContent
    • brDecision
    • brAudit

I’ve already mentioned the latter three components: the BRDP content (brDecisionPointContent), the business rules decision (brDecision), and all the data about the open or closed action related to the decision to be made, who has to take care of those actions and until when, etc. (brAudit).

The only part that was not explained yet is brRelatedTo. This element and brPara are probably the only ones in the brDoc Schema, the names of which don’t give a straightforward meaning for the information they contain. That is because they group various bits information into one conglomerate. But in the first place, brRelatedTo shows how the given BRDP relates to the Specification text, or as in case of project or organization specific BRDP, to the passage of the document where the given BRDP is defined. Or in other words it provides the Chapter and Paragraph numbers (for the S1000D Issue) or numbers of different types of sections in project/organization specific documents.

Seeing the structure above, I am sure you can recognize that what brDoc Schema does is to accommodate the well-established practices of business rules definition processes into an XML Schema.

If you have ever defined business rules in an Excel format, this would be a typical structure of every row in a spreadsheet, where each row would correspond to one business rule decision point.

First, there would be the unique identifier of that BRDP (the attribute brDecisionPointUniqueIdent of the element brPara). Before or after that, there would be a column in the Excel file pointing out the Chap and Para number in the specification text, where the given BRDP is defined (brRelatedTo). Then the title and the definition of the given BRDP come next, just as it is done in Chap 2.5.3 (BRDP Index). In the brDoc Schema, these make part of the element brDecisionPointContent. Further, there is space for one or more decisions to be defined (brDecision), and finally any open actions, due dates, and the responsible persons recorded (brAudit).

There is of course more to brRelatedTo than only the reference to the place in the Specification where the given BRDP is defined. We will address it as well as the other brPara components in the subsequent posts on brDoc Schema.

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.n1510938514okem@1510938514greb.1510938514ennas1510938514us1510938514