Why Does It Make Sense to Generate a Business Rules Index First and a Guidance Document Second?

In this post, our Business Rules trainer Victoria Ichizli-Bartels claims that and explains why a Business Rules Index (or a list of Business Rules) should be the starting point in business rules generation, even before drafting a contract or a Statement of Work.

Most projects start their S1000D implementations with writing contracts and Statements of Work (SOW), sometimes even before even opening the specification.

After that, they create plans for the technical publication based on those SOWs, which are then extended to define the project business rules. The specification is then consulted, and decision points are considered to set the rules.

However, it is often neglected that somewhere in the contracts, SOWs, and technical plans there are already decisions taken which might be redundant or even come into conflict with those made during the business rules definition process. So, the work is done at least twice (and often more frequently) on some of the decision points, which is, of course, a waste of time and money.

I would like to suggest something quite radical here. I recommend that before signing and even drafting a contract you first read Chapter 2.5.2, 2.5.1 (and 2.5) as suggested in the sixth article of Bitesize Business Rules under the title ”Read-me chapters for Business Rules concept in S1000D® issue 4.2.”

Then I recommend that, as often suggested with any large task, you create a bulleted list jotting down the steps to take or draft a brief outline of the business rules document you are about to create.

In fact, S1000D (in its Issue 4.1 and 4.2) already offers such a list in the form of the S1000D Business Rules Decision Point (BRDP) Index.

BRDP Index

The only drawback of this index is that it is an unordered list. By that, I mean that the decision points are listed in a random order. In Issue 4.1, the BRDP sequence follows the chapter and paragraph numbers, but in Issue 4.2 even this order is “lost” by the end of the index since the BRDP unique number doesn’t possess any affinity to the S1000D structure. A side note here, in Issue 4.1 these identifiers just happen to follow the chapter and paragraph sequence of the specification, since that Issue was the first one for which the BRDP Index was created.

The BRDP Index itself has gaps, by missing some implied decision points (even related to the Data Module Code), and it also contains decision points, which result in hundreds of interdependent decisions. The most prominent example of the latter is the BRDP-S1-00007 – Use of optional elements and attributes.

But despite the seeming drawbacks, the BRDP Index is extremely useful. Thus, start with open it in Issue 4.1 or the BR Template from Issue 4.2, depending on which of these two Issues you implement. Next, scan through the BRDP Index and identify main groups of decisions points or topics there (or use for this purpose the BRDP grouping done by others), choose which are relevant to your program, and decide on the BRDP in each of them. Plus of course, check if there are any additional BRDP that you think are necessary for that or another topic.

After that, add any information you think is needed to each decision point and the rule defined for it, including guidance, figures, examples, etc.

Thus, your business rules index, with any identified information attributed to each of its topics and decision points, can and should serve as the master business rules document. You can shuffle its pieces (groups of or individual items) and extract information from them to produce any document you need, including parts of contracts and Statements of Work.

Issue 4.2 Chap 2.5.2 in Para 2.2.1 already gives you an idea, which BRDP should make part of a contract for an S1000D Implementation. These are:

  • BRDP-S1-00003 – Issue of S1000D to be used
  • BRDP-S1-00004 – Information sets to be used
  • BRDP-S1-00005 – Publications to be produced
  • BRDP-S1-00006 – Schemas to be used

You might also want to add some of the BRDP on quality assurance (including frequency of exchange) and several other BRDP of the contractual matter.

These, in my opinion, are:

  • BRDP-S1-00008 – Possible deliverables
  • BRDP-S1-00009 – Frequency of data exchanges
  • BRDP-S1-00017 – Rules for quality assurance (Top level decisions, including the extent of the customer involvement)
  • BRDP-S1-00018 – Rules for first and second verification (Top level decisions, including the extent of the customer involvement)
  • BRDP-S1-00027 – Need of printable data

There might be some other decisions that will affect the costs of the projects, but the above lists outline the major ones you should take care of at the very beginning of your S1000D implementation.

Coming back to the argumentation for the bulleted lists and checklists, they have proved to be the most efficient method to make sure that you didn’t forget anything when performing a task and a project. An S1000D implementation is no different.

If you take the other, more traditional route, and try to develop business rules starting with a statement of work or a contract you might run into the danger of getting lost and repeating yourself.

As a conclusion, the following can be said: the bullet points in a checklist or an index give a clear idea what is already defined and what is missing. A running text hasn’t such an ability. Thus, the most efficient way to go is first to create an outline or a semantically structured index of business rules. The ideal solution will be if you start drafting your BRDP and BR index before your contract and Statement of Work is produced and ratified. But if a SOW or contract are already defined before the business rules definition, as it is often the case, then see which of the decision points have been answered by the contract and SOW and fill them correspondingly in your business rules index. Only after that define what is missing.

And here is an outlook as well as a spoiler alert for the future posts on the BR Bitesize. We will look closer into the brdoc Schema defined in the S1000D Issue 4.2, and what each component of its business rules structure means, as well as how they can be applied. We will do this because by understanding the brdoc schema and BR template data module you will be able to capture your business rules index (list, outline, or whatever else you would like to call it) and steadily enhance it inside your brdoc project data modules. After doing that for decision points in focus, you will be able to generate any guide, and any document, even pieces of a contract or SOW.

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.n1510939432okem@1510939432greb.1510939432ennas1510939432us1510939432