Has anyone defined best practices around design documentation for OPA Rules? Specifically, what is the best approach for reviewing rules in detailed design JADs if the audience is a mix of business and technical folks?
We are currently considering two options but both have strong drawbacks:
1) Write pseudo OPA rules - Drawbacks: complex rules are difficult for JAD participants to understand. also, this approach doesn't poke holes in policy as well as #2
2) Using UML activity diagrams or decision trees that visually describe the decision - Drawbacks: during development it is difficult to write OPA rules based on decision trees.
Would appreciate it if anyone could share their experience. Bottom line - what document do you look at while you write your rules?
The answer depends a lot on the source material you are using for your project.
Are the rules based on existing legislation, regulations, a policy manual etc.? If so, the best practice is to use this material as the starting point for the documentation. Adding too many intermediate transformative steps can increase effort and reduce the mapping from source material to the natural language/tabular OPA rules.
The answer may be different if the rules have not previously been documented.
One approach some customers use is to use the same logical structure that OPA uses to define the rules in a visual tree form. This is not a decision tree (where the decsions are at the leaves), rather it is the same top-down "this decision is reached if..." structure, where for each node the children are connected with either "and"s or "or"s. These forms then translate easily into the actual rule documents, and it has the advantage of "poking holes" just as effectively as it would if you were actually modeling the rules in OPA.
Another approach that works well is to co-develop the rules in a more agile fashion with the policy expert and rule author working side-by-side. Then there is no intermediate step.
In this case, it's also easier to capture test cases with expected results as you go.