How to document business rules so people actually use them

Ask most organisations for their business rules and you will get one of three things: a policy PDF from three years ago, a spreadsheet only one person understands, or a shrug and "it's in the system".

Documenting business rules is not hard. Keeping the document true is. Here is a method that works.

Why business rules documents go stale

• The document and the system are separate, so one changes and the other does not
• Rules are written in legal or technical language nobody else reads
• Numbers are buried in paragraphs, so updating a limit means rewriting prose
• There is no owner, so nobody feels responsible for keeping it current
• There is no version history, so nobody knows what was true last quarter

The fix is to document rules in a way that makes them easy to change, and ideally to make the documentation and the working rule the same thing.

Step 1: Start with the decision

Do not start by listing rules. Start by naming the decision they support, as a question:

• Who must approve this purchase order?
• Can this customer have this credit limit?
• Is this supplier ready to trade?
• What discount can this rep give?

One decision, one document. It keeps each document short and gives it a clear owner.

Step 2: Name the owner

Every decision needs one named owner: the person who can say "yes, that is our policy". Usually that is a finance director, head of credit, head of procurement or operations lead. Not IT. IT builds it; the business owns it.

Step 3: List the facts

Write down every fact the decision uses, with where it comes from. For a credit decision: requested limit (from the order), overdue balance (from the ledger), risk score (from the agency). If you cannot say where a fact comes from, the rule cannot run reliably.

Step 4: Write each rule as one sentence

Use a consistent pattern: when [condition], then [answer], because [reason].

• When the account is on credit hold, then refuse, because we do not extend credit to accounts on hold.
• When the order is capital spend, then add the finance director, because capital needs board-level oversight.

The "because" matters. It is what you will need when someone asks why, and it stops rules being removed by someone who does not understand them.

Step 5: Separate the numbers

Keep thresholds, bands and lists out of the sentences. Instead of "orders over 10,000 go to the finance director", write "orders above the finance director band go to the finance director", and keep the bands in a table.

This single change makes documents far easier to maintain. When a limit moves, you update one row, and every rule that uses it stays correct.

Step 6: Add worked examples

For each decision, add five to ten real examples with the expected answer. Include the awkward ones: the edge of a band, the exception, the case that caused an argument last year. These examples become your test cases.

Step 7: Version it

Record what changed, when, and who approved it. When audit asks what the rule was on a given date, you should be able to answer in minutes.

A simple template

For each decision, capture:

1. Decision: the question, in one line
2. Owner: the named person
3. Facts: each input and its source
4. Rules: when, then, because
5. Reference data: the tables and lists the rules use
6. Examples: real cases with expected answers
7. Version history: what changed, when, who approved

The best documentation is the rule itself

Even a good document drifts from the system over time. The strongest approach is to make the working rule readable enough that it is the documentation.

That is how Condexa is designed. Each decision is a visual workflow that reads step by step. Reference data sits in lookup tables and lists the owner can see and edit, and can import or export as files. You run your worked examples as tests and read the trace before publishing. Versions are kept as Draft, Active and Inactive, so you always know what was live. And every call is recorded in run history, so you can see how the rule behaved in practice, not just how it was meant to.

Next steps

See how the decision trace and versioning keep rules explainable, or read about the risk of tribal knowledge. For inspiration, browse our business rules examples. Then bring one decision to a 30-minute demo.