
Documenting BRF+ deliverables
When you decide to embrace the Business Rule Framework for complex decision making, then no technical specification is required. The tool generates all object-oriented ABAP code automatically. Apart from reducing the deployment lead-time, avoiding the need for documentation will be a blessing for many.
Face it, writing documentation is not a favourite activity for many. Even though this action is part of the job for a business analyst and developer, the lack of enthusiasm often reflects in the delivered quality. Writing is a skill you need to cultivate.
Still, up-to-date and accurate and complete specifications are vital to achieve and support a stable system.
Any change in the system starts with business requirements, converted into a functional and technical specification. Each document has its purpose, supported by approval procedures.
That is a beautiful theory, but reality looks so different.
Luckily you can document within the Business Rule Framework. The GENERAL section of every BRF+ object has its dedicated DOCUMENTATION tab. If you agree to have that filled in and validated, then you already safeguarding that anyone with minimal BRF+ knowledge can understand the purpose of the object.
You can write documentation for a function, ruleset, rule, expression and data object. Your mission is to add enough content to allow any colleague to understand its purpose. Spend special attention to WHY the BRF+ object exists and the expected result.
Remember to avoid repeating yourself. When a rule is using an expression, avoid explaining the details for the expression while describing the rule.
Documentation for a function can focus on the signature and the result, and even highlight what happens after you return the result. Also, list the rulesets and list the reason for the priority.
The ruleset documentation can highlight the need for a precondition. Besides, list the additional variables and the expression to fill the initial value (when applicable). Finally, describe the details in the rule and highlight the reason for using expressions.
Continue with each expression, detailing its specific purpose.
Remember, only feed the information required to the consultant analysing the BRF+ object.
Test the quality of your documentation by asking for a second opinion. Let a colleague analyse a BRF+ function and all its components by only reading the explanation stored for each object. Verify if the content makes sense and whether the actual configuration reflects the instructions.
Just sit back and observe how someone interprets the available information. Make adjustments where there is ambiguity. Then decide whether to update the functional specification, pasting as much content in the DOCUMENTATION tab as possible.
Following this advice will increase the quality of the required documentation before you deploy the BRF+ application changes into the production environment.