There are things in the S1000D that are self-explanatory, and others are understandable only on the second look. And then there are things you take for granted but don’t know why they are defined as they are. Only those who were present during the development of one or another Schema will know the reasons behind the decisions taken. And surely not for all of them.
I’ve been lucky to have been coordinating the creation and development of the Business Rules Document (brdoc) Schema, which can be used for any type of a business rules document, be it in the form of a style guide (flowing text), or an index (list) of rules. Due to the chair position, I hold in the Business Rules Working Group (BRWG), I have been present and involved in almost all its changes and improvements. That gave me a unique insight, a part of which I would like to share.
This particular insight is necessary to understand the structure of the central business rules building block inside the brdoc Schema, which is the element <brPara> or business rule paragraph.
But before I explain the reasons behind the structure of the business rule paragraph, let me first address its components.
There are two principal components for each business rules paragraph: a decision point and a decision taken at this given point.
The business rules decision that is the decision you make at any given decision point has a dedicated element. It is <brDecision>. However, the business rules decision point doesn’t have any separate element dedicated to it.
Such a structure might appear a bit strange at the beginning, but if you look closer, you might see the reasons why it is like that.
Let’s explore the reasons together.
There can be business rules decisions without any corresponding decision points, like default BREX rules defined by S1000D or the existing regulations for a project or organization.
When you look however at a decision point, it is always incomplete without a decision.
Therefore, if there is a decision point, then all decisions made concerning it, can also be attributed to it and its unique identification number.
At the beginning, we named this construct <brDecisionPoint>. But during the analysis and discussion process, we realized that when a decision is made, then the whole construct stops being just a decision point. It rather starts being something else, a complete section — or paragraph — containing both business rules decision point and the corresponding decisions. That is why it is a <brPara> now.
If you happen to search where to look for the title and content of a business rules decision point inside a brdoc data module, then look for the element <brDecisionPointContent>, a child of the element <brPara>. It contains an element <title> as well as the element <brDecisionPointText>, which contains text fragments such as starting with “Decide whether to…” and similar. The unique identification number is captured by the attribute brDecisionPointUniqueIdent on the element <brPara>. Refer to the Chap 4.10.1, Para 6, in S1000D Issue 4.2 for a business rule paragraphs documenting a decision point with and without decisions taken.
If you have questions on brdoc Schema, how you can apply it, or why it is structured the way it is, then don’t hesitate to find me at the joint ATA e-Business Forum and S1000D User Forum in Amsterdam this month.
Webinar: S1000D is More than a PDF file, default BREX, and XML Schemas.
Join Victoria Ichizli-Bartels for her Webinar: S1000D is More than a PDF file, default BREX, and XML Schemas. In this 2-hour webinar, you will learn about the richness of information and tools S1000D is offering in its download packages and will learn what those objects are suitable for. Book your space on our webinar which will include:
- Various objects inside an S1000D download packages for different Issues of S1000D (including Issue 4.2),
- Which of the objects are highly useful, and which are less useful, for example they are covered by other more comprehensive objects,
- What bits of information inside S1000D text are great tools on their own and should often be used,
- Secrets on how information changes from one S1000D Issue to another.