Building my last application, everbody started to lose control over the increasing complexity of business rules, which would be added every week - most of all the app owners themselves. In the end, we had to explain the behaviour of their own app to them, because they forgot what they had defined a few weeks before.

With my current app, I see a similar situation approaching; in their daily business, the app owners face issues with singular clients which they usually convert into a business rule, like: if the current client is xy, use a different notification template.

We tried to use Lucidcharts to create some sort of diagram or wireframe to keep track of what the app is actually supposed to do. I would mark a rule in the wireframe with an ID, ie #01, and then refer that ID to the actual code. But it's hard to get everybody involved, especially non-tech people (business owners).

What would be the format to keep an organized catalog of business rules, as a reference for the coder, the project manager and the business owner?

And if someone feels like voting down this question, please explain why.

2 Answers 2


Requirements need to be documented. You are already attempting to do that, but requirements are often broken down into a number of categories:

  • Business requirements — Things like "A blog post requires a title" would be considered a business requirement.

  • Functional requirements — These spell out in greater detail how the application behaves. Technical jargon starts to crop up: "If the blog post title field is empty, display this validation message: "The title is a required field"

  • Technical requirements — Fraught with technical jargon, these are almost incomprehensible to the business: "Use the RuleFor(...) method in FluentValidation to mark the PostTitle property "not empty" in the BlogPostForm view model

There are many tools out there that specialize in organizing requirements, but tool recommendations are off topic for this site.

Beyond requirements, a development methodology called Behavior Driven Development (BDD) (utilizing the Gherkin language) essentially allows you to write user acceptance tests in a natural language format, and using bindings to a programming language, these tests become actual functioning tests that can interact with a real user interface and database.

An advantage of BDD is your business requirements become tests that pass or fail as the application evolves. In order to keep the tests passing, you need to update the business rules. In order for the application to keep enforcing new or changed business rules, you need to update the application after rewriting the rules. It forces you to keep the documentation up to date, because you have failing tests.

  • So does BDD help in covering the documentation of all those three categories?
    – Hans
    Commented Oct 5, 2018 at 18:01
  • BDD takes care of business requirements. It can be used to document functional requirements, but they are no longer behavior driven tests - and that's OK. It's fine to use cucumber to automate a QA testing suite. BDD and cucumber can't be used to document technical requirements. Commented Oct 9, 2018 at 12:59

Separate the authoring of rules from the deployment of updates to the software.

If you have a lot of business rules that are of the if-then variety, you may want to consider using a Business rules engine, which helps provide a UI for the management of the rules, performed by product owners, and an API for the execution and enforcement of the rules, which is done by software (and the developers writing it).

If your rules are growing and changing rapidly, it's probably hard on the whole team to go through the whole develop-test-build-deploy cycle for each rule. A rules engine will help decouple the creation and "deployment" of rules from the deployment of updates to the software.

For instance, one open-source rules engine for Java is Drools.


This would be a bigger upfront cost than using a BDD framework or documenting rules with a BDD-style language, since it involves setting up a running system to manage the rules authoring, but the advantage is that rule changes can get to production much faster than with BDD. It may or may not be appropriate for the volume of rules in your software, but if the rules are changing faster than the software can change, this is an option to discuss with your team.

  • This sounds interesting, but now I don't know which path to take. In my projects, business rules didn't really change, but they nested, ie. rule A become A1 and A2, A1 becomes A1.1 and A1.2 etc.
    – Hans
    Commented Oct 5, 2018 at 19:24
  • 1
    "Nest" is a type of change.
    – Eric
    Commented Oct 9, 2018 at 12:36
  • Yes, I agree. My project manager would prefer a visual style of defining business requirements. Unfortunately people decided to downvote your suggestion w/o giving an explanation, which provides no learning value.
    – Hans
    Commented Oct 9, 2018 at 13:43
  • I'm not the down-voter, but I think it may be due to recommending a programming or software design pattern, rather than addressing the problem of documenting these rules. Code implements the rules, and therefore a "business rules engine" is also implementation, not documentation. Commented Oct 9, 2018 at 17:29
  • Thanks for your thoughts. That's unfortunate, since I was certainly not trying to recommend a pattern instead of documentation! The BRE I linked to as an example has on its front page screenshots of how you can use it to visualize how rules interact.
    – Eric
    Commented Oct 9, 2018 at 20:00

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.