Stay with me folks, this is not a light topic but it will be worth it…
In Issue 4.2 of the S1000D Specification there was the introduction of a couple of new schemas. One of the new schema’s was brDoc, and the use of this schema will be the focus of this blog.
This schema has been implemented to provide projects with the ability to create Business Rules. Up until Issue 4.1 the option was to use the Descriptive schemas and use the information code of 022. With Issue 4.2 we can now use the brDoc schema and information code 024 to build our Business Rules.
The brDoc schema is very similar to the descriptive structure with some additional features. We use the <brLevelledPara>, instead of the <levelledPara> in Descriptive. This allows you to start writing descriptive information about how the S1000D project is to be implemented.
Once you have inserted the <brLevelledPara> the choices you can have are:
- title
- brPara
- para
- plus additional elements
When using the <brPara> you are going to document the information about your decision points for the implementation of S1000D for your project. All requirements should be based initially, on the rules that have been identified by the S1000D Business Rules Decision Point Index (BRDP). As you are identifying the requirements under these Decision Points you may also identify additional decisions that the business/project needs to define. As an organisation you will build your own BRDP Index codes.
The minimum (mandatory) structure required is demonstrated below:
Looking at the above structure you can see that just by using the mandatory elements and attributes, there is a range of information that we need to expand on.
Looking at the structure we need to dig deeper on what can be included in <brPara>.
Attribute brDecisionPointUniqueIdent – This attribute is used to identify the BRDP the para relates to:
Element <brRelatedTo> – This element allows you to reference to the details of the BRDP. This can either be contained in a Data Module, External Technical Publication or within the brDoc document. How you manage the BRDP information is a decision that the project needs to decide on when you commence writing the brDoc Data Module.
Element <brCategoryGroup> – This element allows you to identify what category (refer to Chap 2.5.1 – Business Rules – Categories and Layers) the BRDP relates to.
Attribute brCategoryNumber – This attribute allows you to identify the category that the BRDP relates to. You are able to define how you will identify the categories and this will be entered into this attribute.
Element <title> within the <brCategoryGroup> – The title element allows you to provide descriptive details about the type of category this relates to.
Element <brCategoryDescription> – This element contains a child element <para> and allows you the details about what this category.
Element <brDecisionPointContent> – This element contains the details about what the BRDP decision is.
Element <title> –The element allows you to enter the title about what decision needs to be made for the decision point.
Element <brDecisionPointText> – This element allows you to enter details about the decision.
Element <brDecision> – This element allows you to define what the decision is for this BRDP. Available options are:
- <brDecisionPending>
- <brDecisionText>
- <brDecisionValueGroup>
- <brDecisionExplanation>
You need to identify what is the decision and which of these element these elements you wish to use:.
Element <brDecisionPending> – When this element is inserted indicating that no decision has yet been made for the project.
Element <brDecisionText> – This allows you to enter a description of what is the decision.
Element <brDecisionValueGroup> – This allows you to define the decision (yes or no) in the <brdecisionValue> and you can include what the decision is.
Element <brDecisionExplanation> – This allows for you to add additional information which cannot be included in the <brDecisionText> element.
It is a project decision as to whether the brDoc schema is utilized. If the decision is made to use the brDoc schema then the project must also decide on the structure that will be used. As per any decision that is made for the implementation of S1000D for a project, this information should be recorded into the Business Rules. Consideration must be made on how this will be done and the BRDP Index should be used as a guide.
The project should also consider any other decisions that are necessary that are greater than the BRDPs that are contained within the specification. These decisions should be documented and the project should develop their own BRDPs and BRDP Index. These should be included in the brDocs Data Module.
Business Rules and BRDP Index provides projects a method of managing the implementation of S1000D into their technical documentation. Once the brDoc and Business Rules have been written this becomes a point of reference for all members of the technical team. Once the brDoc has been created you are then able to create your BREX, as a BREX is used for validation against content when authoring. Enure that you have a document that contains all necessary information to ensure that your technical authors are writing content that is valid to your Business Rules.
