This article examines how to use tabulation to write better business rules. If you’re not writing business rules, well, you should be. Fortunately, the very same guidelines apply to writing requirements in general, so there is much to be gained on all fronts.
Using lists of indented bullet items is called tabulation (after the keyboard tab key used to indent). Tabulation is a stylistic device commonly applied in legal and other forms of writing for simplification and clarity.
Example of contractual provisions without tabulation [1] …
For a one-year period after the Term, the Executive shall not employ any person who was an employee during the Term. In addition during that period, the Executive shall not interfere with the relationship between the Company and any of its employees.
Tabulated version …
For a one-year period after the Term, the Executive
a. shall not employ any person who was an employee during the Term; and
b. shall not interfere with the relationship between the Company and any of its employees.
The tabulated version is more approachable and much easier for the reader to assimilate correctly.
As the above example illustrates, in tabulation the subject matter must be common to each subsequent item. Specifically, the phrase at top, "For a one-year period after the Term, the Executive", applies equally and directly to each item below it. Showing common subject matter at the top of a statement is a basic rule for tabulation. Fortunately it happens to be one of the fundamental guidelines of RuleSpeak® [2].
This article examines how to use tabulation to write better business rules. If you’re not writing business rules, well, you should be. Fortunately, the very same guidelines apply to writing requirements in general, so there is much to be gained on all fronts.
Using Tabulation
The RuleSpeak keyword "the following" is used to organize multiple conditions in a single business rule statement. Otherwise the conditions would need to be expressed using either:
-
Strings of "and's" and "or's". Business people and others often find such strings difficult and tedious to comprehend.
-
Multiple statements. The overall number of business rule statements to be managed is already likely to be significant. The prudent approach is to reduce the total, rather than increase it unnecessarily.
The RuleSpeak keyword "the following" is always accompanied by [3]:
1. A list of indented bulleted conditions.
2. A threshold indicating how many of the conditions are required to be true
Common thresholds include all the following and any of the following.
RuleSpeak tabulation in no way replaces or substitutes for decision tables. If a decision table can be used to represent some business rules, it should be [4]. A very large number of business rules, however, simply cannot be represented in decision tables in any meaningful way.
This basic rule for tabulation also applies to expressing business rules. The following example illustrates how the common subject matter in three separate business rules can be unified, thus enabling consolidation. The common subject matter has been italicized for emphasis only.
Example without tabulation …
A claim must be considered potentially fraudulent if the claimant has made more than six claims in the last two years.
A claim must be considered potentially fraudulent if the claimant has owned more than five vehicles in the last year.
A claim must be considered potentially fraudulent if the claimant has a history of fraudulent claims.
Tabulated version …
A claim must be considered potentially fraudulent if any of the following is true:
▪ The claimant has made more than six claims in the last two years.
▪ The claimant has owned more than five vehicles in the last year.
▪ The claimant has a history of fraudulent claims.
Now there is only a single business rule statement instead of three.
All business rules properly expressed under RuleSpeak are declarative. Note in the revised version of the example above, the tabulated conditions are bulleted rather than numbered or lettered (as was the case in the earlier contractual example).
This bullet convention avoids any suggestion of sequence, importance, or priority. (If priority is intended, the statement must mention priority explicitly.) Since the order in which bullets are listed is logically immaterial, they can appear in random sequence – or better, in the sequence readers find most friendly.
In the example above, note that each bulleted condition begins with "The claimant has". This phrase could also be removed and consolidated with the common subject matter. How far unification of all common subject matter in a given case should be taken is a judgment call. The answer should hinge on what proves the most readable and business-friendly.
Why Use Tabulation
There are important reasons to use tabulation in writing business rules. It provides structure both for thinking about business rules and laying them out in a manner that lends itself naturally to asking questions and identifying ambiguities, gaps, and inconsistencies. Understanding the related issues can enhance your skills in writing business rules – and business requirements –significantly.
Eliminating Ambiguity
1. Use of "and" where "or" is actually meant
Example …
A shipment may be made only to the European countries United Kingdom and The Netherlands.
This business rule statement could be interpreted to mean any given shipment may be made only to both countries listed. Sending the same shipment to both countries is almost certainly not what is intended.
Tabulated version …
A shipment may be made only to one of the following European countries:
▪ United Kingdom.
▪ The Netherlands.
Using tabulation along with a clear threshold ("… only to one …") eliminates the mistaken use of "and" and eliminates the potential ambiguity.
2. Potential ambiguity in what is "and'ed"
Consider the following statement (from a lawyer) …
"Our agreement is that our firm shall receive $3,750.00 in fees and reimbursement for costs advanced."
The statement can be read either as:
1. Lawyer's interpretation: "... our firm shall receive $3,750.00 in fees [and reimbursement for costs advanced]."
2. Client's interpretation: "... our firm shall receive $3,750.00 in [fees and reimbursement for costs advanced]."
A lawyer should know better. The statement should have been written as below.
Tabulated version …
A client must pay all the following:
▪ $3,750.00 in fees.
▪ reimbursement for costs advanced.
3. Potential ambiguity in whether "or's" are exclusive or inclusive
Natural language generally makes no assumption about whether an "or" is meant to be exclusive or inclusive. The ambiguity can be eliminated, of course, by stating "exclusively" or "inclusively" explicitly in each case. For business rules, however, tabulation is generally much more effective.
Example with an ambiguous "or" …
A project must be considered active if it has a manager, a budget, or a sponsor.
Does the statement mean exactly one or at least one of the three listed items? Different readers may make different assumptions. Let's assume at least one is intended.
Tabulated version …
A project must be considered active if at least one of the following is true:
▪ It has a manager.
▪ It has a budget.
▪ It has a sponsor.
4. Potential ambiguity in strings of "and's" and "or's"
Natural language also generally makes no assumption about the precedence of "and's" and "or's" – i.e., which logically should be applied first in a statement that includes both. Consider the statement below from a menu for a restaurant [5].
With each entrée, you get a vegetable and salad or soup.
Which of the interpretations below is correct?
1. With each entrée, you get (a vegetable and (salad or soup)).
2. With each entrée, you get ((a vegetable and salad) or soup).
This ambiguity can be addressed, of course, by punctuation or parentheses (as above). The result, however, is seldom as straightforward or as reader-friendly as desirable, especially where the number of "and'ed" and "or'ed" conditions increases. Tabulation eliminates the ambiguity. Let's assume the first interpretation above is the correct one.
Tabulated version …
With each entrée, you get the following [6]:
▪ a vegetable.
▪ salad or soup.
Enhancing the Readability of Statements by Using Tabulation
1. Awkward sentence construction
Tabulation can sometimes straighten out very awkward sentence construction, bringing it at least to the point that it can be validated and corrected (if needed).
Example …
A territory must not include any non-candidate traditional gas station if it includes any ultra-service or food outlet; must not include any ultra-service if it includes any non-candidate traditional gas station or food outlet; etc.
Tabulated version …
A territory must not include more than one of the following:
▪ Non-candidate traditional gas station.
▪ Ultra-service.
▪ Food outlet.
2. Repetition of keywords
In RuleSpeak each statement of a business rule should have one and only one rule keyword. Experience has proven this to be an important practice in enhancing clarity.
Example …
The status of a closed loan must be 'approved' and the category must not be 'high-risk' if it is for a restaurant.
The rule keyword "must" appears twice in this statement. Does the "if" condition at the end apply to both "must's" or just to the latter? Let's assume the condition applies to both.
Tabulated version …
All the following must be true for a closed loan if it is for a restaurant:
▪ The status is 'approved'.
▪ The category is not 'high-risk'.
The revised statement centers on a single rule keyword in the common subject matter at the top of the statement. The qualification "for a restaurant" now clearly applies to both bulleted conditions.
3. Front-Loaded Qualification
Putting multiple qualifications at the front of a business rule statement tends to make it 'dense' and hard to comprehend. Putting such 'heavy lifting' toward the end of the statement instead produces a statement much easier to read. Tabulation makes this simplification possible.
Example ...
A machine owned by an employee included in a team assigned to a high-security project must not be serviced by a company located in a country suspected of terrorist activity.
Tabulated version …
A machine must not be serviced by a company if all the following are true:
▪ The company is located in a country suspected of terrorist activity.
▪ The machine is owned by an employee included in a team assigned to a high-security project.
As the tabulated version illustrates, keeping the common subject matter as simple as possible provides a mental anchor for the reader in then wading through the qualifications.
Grouping Statements to Enhance Manageability
Tabulation can be used in certain cases to unify business rule statements that could actually stand on their own [7]. Such unification eliminates the fragmentation of business logic that might otherwise occur. It also provides single points of coordination for the related business rules, to ensure they can be located, reviewed, and potentially revised in concert.
1. Many things that must all be true for something
Often there are many things that must be true for some subject matter of interest. For example, the following six business rules statements all indicate things that must be true for claims.
Individual business rule statements …
A claim must indicate which active policy covers it.
A claim must indicate who the claimant is.
A claim must indicate what health care was provided.
A claim must indicate what health care provider provided the health care.
A claim must indicate what the injury/illness was.
A claim must indicate when the initial date of the injury/illness was.
These six statements could be among hundreds (or thousands) of other business rules. A better approach is to unify them using a single business rule statement with tabulation.
Tabulated version …
A claim must indicate all the following:
▪ which active policy covers it.
▪ who the claimant is.
▪ what health care was provided.
▪ what health care provider provided the health care.
▪ what the injury/illness was.
▪ when the initial date of the injury/illness was.
This single business rule statement replaces the earlier set of six. All the bulleted conditions must be true. The statement provides a single point of coordination for all the things that must be indicated for a claim.
2. Something that must be true if any of multiple conditions is true
A somewhat more complicated pattern and opportunity for consolidation occurs when something must be true if any of multiple conditions is true. For example, the following five business rule statements each indicate the same thing for an order must be true – that it be credit-checked – if a particular condition holds true.
Individual business rule statements …
An order must be credit-checked if the order total is more than $500.
An order must be credit-checked if the outstanding balance of the customer's account plus the order amount is more than $600.
An order must be credit-checked if the customer's account is not older than 30 days.
An order must be credit-checked if the customer's account is inactive.
An order must be credit-checked if the customer is out-of-state.
These five statements could be among hundreds (or thousands) of other business rules. A better approach is to unify them using a single statement with tabulation.
Tabulated version …
An order must be credit-checked if any of the following is true:
▪ the order total is more than $500.
▪ the outstanding balance of the customer's account plus the order amount is more than $600.
▪ the customer's account is not older than 30 days.
▪ the customer's account is inactive.
▪ the customer is out-of-state.
This single business rule statement replaces the earlier set of five. It provides a single point of coordination for all the things that require an order to be credit-checked.
Author: Ronald G. Ross is recognized internationally as the ‘father of business rules.’ He is Co-founder and Principal of Business Rule Solutions, LLC, where he is active in consulting services, publications, the Proteus® methodology, and RuleSpeak®. Mr. Ross serves as Executive Editor of BRCommunity.com and as Chair of the Business Rules Forum Conference. He is the author of nine professional books, including his latest, Building Business Solutions: Business Analysis with Business Rules with Gladys S.W. Lam (2011, http://www.brsolutions.com/bbs), and the authoritative Business Rule Concepts, now in its third edition (2009, http://www.brsolutions.com/b_concepts.php). Mr. Ross speaks and gives popular public seminars across the globe. His blog: http://www.ronross.info/blog/ . Twitter: Ronald_G_Ross
[1] From Drafting Contracts: How and Why Lawyers Do What They Do, by Tina L. Stark, Aspen Publishers — WoltersKluwers, 2007, p. 211.
[2] For more about RuleSpeak, refer to www.RuleSpeak.com (free).
[3] For comprehensive usage guidelines, refer to Part 3, Tabulation of Lists in RuleSpeak®: A Primer – Using “The Following” Clause, by Ronald G. Ross, 2013, available (free) on http://www.brsolutions.com/IPSpeakPrimers
[4] For explanation, refer to Decision Tables: A Primer — How to Use TableSpeak™, by Ronald G. Ross, 2013. Available (free) on www.BRSolutions.com
[5] Berry, Daniel M., Erik Kamsties, Michael M. Krieger, and WillenkenLohStris Lee & Tran. [November 2003]. From Contract Drafting to Software Specification: Linguistic Sources of Ambiguity: A Handbook, (Version 1.0). ["Ambiguity Handbook"], p. 44. Available [1/5/2013] at: http://se.uwaterloo.ca/~dberry/
[6] Note that an “or” remains in the second bullet. For this simple example that “or” is probably innocuous. In more complicated examples it easily might be misinterpreted. It can be eliminated by nested use of “the following”. Refer to the usage guidelines in Part 3, Tabulation of Lists in RuleSpeak®: A Primer – Using “The Following” Clause, by Ronald G. Ross, 2013, available (free) on http://www.brsolutions.com/IPSpeakPrimers
[7] In the OMG standard Semantics of Business Vocabulary and Business Rules (SBVR), the underlying principle is called Severability. Severability is the business counterpart to what in propositional logic is often called the universal 'and'. In general, this assumption permits individual statements of manageable size to be expressed – a very good thing. In the strictly-limited cases described here, however, it works against overall manageability.