≡ Menu

A reader asks – how to document decision logic


I got an interesting question last week:

In you experience do you believe that the rules editors will become self documenting tools and, if so, is there any danger to this?
With regard to products I have used in the past I am not convinced they have evolved sufficiently to do this and I always see users maintaining separate spreadsheets of rules identical to the solution, which inevitably brings lots of duplication.
In an ideal world I could see these tools becoming self documenting, for example you can export from your editor a  formatted doc with your propositions or eligibility rules, but I haven’t worked on a tool yet that truly allows the business users the flexibility of the dreaded excel spreadsheet

This is one of the most interesting questions when it comes to successful decision management implementations. Several positions are taken by different groups ranging from those that argue the rules in a good business rules or decision management system are self-documenting and nothing more is required – the business users will just use the rule maintenance environment to manage the rules – to those who want to keep the original source documents, a natural language form of those rules, a formal (but not executable) version of the rules AND the execution environment. With this in mind, some guidelines:

  • It is useful for the business users to be able to specify their rules in their own words without having to worry about data implementation, execution syntax or rule templates. This will likely be outside the business rules or decision management system.
  • Not everything in a regulation, a policy or even an expert’s know-how is a rule so while a source might result in many rules, the rules do not completely define the source and so cannot substitute for it. You need to know the rules and the source.
  • It is essential that the implementation be traceable back to the original source where that source is “external” like a regulation or a company policy and doing this through a less constrained, natural language form can be very effective.
  • Not all rules are created equal and some need more documentation than others.

Where rules come from a formal source, like a regulation, I tend to think it is useful to capture the regulation as a source and then to manage a set of natural (business) language rules that represent the parts of that regulation that apply to the business. This will ensure the implementation is done right and this should be maintained as the source regulation changes for the same reason. In most cases I don’t think going from the implementation to the source regulation directly is as effective. If the business users can maintain the natural language rules AND the implementation rules (using templates or metaphors) so much the better. Using a tool like RuleArts’ RuleXpress or New Wisdom’s RuleGuide and then using the implementation repository to link back to these definitions is much more effective than using a spreadsheet to list the rules.

Where rules are more dynamic and temporary, as in marketing promotion for example, I don’t think this is helpful. Here I would suggest that folks take the set of rules that were in force when the project was started and use natural language forms to describe them so that they can be modeled accurately. Once the model of what a promotion rule, for instance, looks like is established I don’t think the interim rules have ongoing value. In this case the implementation rules are constrained by the model and should be managed by the business as the rules-of-record. The ability of products to integrate with tools for documentation – ILOG’s very nice integration with Office for instance – helps here as it allows non-tool users to see the rules in a format that feels more familiar. The basic premise that the rules are the implementation is key to these kinds of rules.

Obviously there is a gray area in between but that’s why there are consultants like me that people can hire 🙂