How to document business rules

Ask five people at your company "what happens when an order is over €5,000?" and you'll often get five different answers — one from the sales manager, one from the script a developer wrote six years ago, one from an Excel macro finance still uses, and two people who just shrug. That's not a training problem. That's a documentation problem: your business rules exist, but they live in scripts, in one person's head, and in tribal knowledge that leaves the building every time someone quits or retires.

This article walks through how to actually find those hidden rules, write them down in a way that survives staff turnover and system upgrades, and keep the documentation from going stale the moment someone changes a script.

What counts as a "business rule" anyway?

A business rule is any decision logic your company applies consistently, whether or not it's written down anywhere. Some examples that show up constantly in FileMaker and ERP systems:

• Orders above a certain value need manager approval before they're invoiced.
• Customers in country X get VAT calculated differently than customers in country Y.
• A product can't ship if its inventory count drops below a safety stock threshold.
• Discounts stack in a specific order — volume discount first, then loyalty discount, never the reverse.
• A support ticket auto-escalates if it hasn't been touched in 48 hours.

None of these are "features." They're decisions your business made at some point, usually informally, that then got baked into a script, a calculation field, or a conditional formatting rule — and never written down anywhere a human can read without opening the developer tool.

Why does this matter more in custom software than off-the-shelf software?

In a package like SAP or Exact, business rules are at least partially visible in configuration screens — you can go look at the VAT table or the approval matrix. In custom-built FileMaker or ERP systems, the rule is often just... a script step. If [Orders::Total > 5000] Set Field [Orders::Status; "Needs Approval"]. That line works perfectly. Nobody can find it in six months except the person who wrote it, and it will never show up if you search for "approval process" in any manual, because there is no manual.

This is the core risk covered in our related piece on how to make custom business software reliable and transferable: a system can be technically flawless and still be a liability if the logic inside it isn't documented anywhere a new developer, IT manager, or auditor can find it.

Where do business rules actually hide? (the usual suspects)

1. Scripts and script triggers. The most common hiding spot. A script named "Process Order" might contain five distinct business decisions with no comments.
2. Calculation fields. A field called cDiscount might encode an entire tiered pricing policy in one nested Case() statement.
3. Layout-level conditional formatting. Rules like "turn the row red if overdue by more than 10 days" are real business logic, but they live in a layout inspector panel almost nobody opens.
4. Validation rules and required-field settings. "A purchase order can't be saved without a cost center" is a policy, not just a technical constraint.
5. Someone's head. The riskiest one. "Oh, we never ship to that customer on Fridays" — said out loud once a year, written down nowhere.
6. Email templates and PDF layouts. Wording like "payment due within 14 days unless customer is on Tier A terms" is a business rule hiding in a template.

How do you actually find and extract these rules? A step-by-step approach

Step 1: Audit scripts and calculations systematically

Go file by file, script by script. For each script, ask: "does this contain an If, a Case, or a threshold value?" If yes, that's a candidate business rule. Don't try to do this in one sitting for a large system — budget it as a real project task, not a side task squeezed between tickets.

Step 2: Interview the people who "just know"

Sit with the sales manager, the warehouse lead, the finance person — and ask them to walk through their process as if training a new hire. Record it (with permission). You will hear things like "oh yeah, we always double-check with the customer if it's a rush order over 20 units" — a rule that exists nowhere in the system and is currently only enforced because that one person remembers to do it manually.

Step 3: Write each rule in the same simple format

Don't write prose paragraphs. Use a consistent structure so rules are scannable and comparable:

• Rule name: Manager approval for large orders
• Trigger: Order total > €5,000
• Action: Order status set to "Needs Approval"; email sent to sales manager
• Where implemented: Orders script "Process Order", step 12
• Owner: Sales department
• Last verified: date

This format matters more than it sounds — it's what makes the documentation actually usable later by someone who isn't you.

Step 4: Cross-check the written rule against what the system actually does

It's common to discover the documented "official" rule and the actual script no longer match, because the script was patched during a deadline crunch two years ago and the policy documentation was never updated (because there wasn't any). Test cases, not assumptions: run a real order through the system at exactly €5,000.01 and see what happens.

Step 5: Store the documentation somewhere developers will actually open

A business rules document that lives in a forgotten SharePoint folder gets ignored. Options that work better in practice:

• A dedicated wiki page linked directly from the project's version control.
• Comments embedded directly in the script itself, plus a summary doc that links to the script name.
• A structured rules table inside the system itself (a BusinessRules table with fields for trigger, action, owner) that both technical and non-technical staff can browse.

How do AI tools change this? (and where Klai fits in)

Manually auditing hundreds of scripts for hidden logic is tedious, and tedious tasks get skipped. This is where AI assistance inside FileMaker — like Klai — genuinely earns its place, rather than being a gimmick. Used well, an AI layer can:

• Scan a script and produce a first-draft plain-English description of what it does, which a human then verifies and corrects — much faster than starting from a blank page.
• Flag calculation fields with unusual complexity (deeply nested Case() or If() logic) as candidates worth documenting first.
• Answer a staff member's question in plain language ("why did this order need approval?") by referencing the documented rule, instead of that staff member having to ask a developer.

The caveat: AI-generated descriptions of what a script does are not the same as documentation of what the business intends. Always have a human owner confirm the rule is correctly stated — AI accelerates the first draft, it doesn't replace the interview with the sales manager.

Does the layout layer matter for documenting business rules?

More than most teams assume. When business rules are only expressed as logic buried in scripts, the person entering data has no idea a rule even exists until it fires. A modern forms/layout layer like FMBetterforms lets you surface the rule at the point of data entry — for example, showing a visible warning "This order exceeds €5,000 and will require manager approval" right on the form, rather than hiding that as an invisible script action. This does double duty: it makes the system more usable, and it forces the rule to be explicit and visible, which naturally makes it easier to document because it's no longer hidden two layers deep in a script.

How do you keep business rule documentation from going stale?

This is where most documentation efforts quietly die. A few practices that actually hold up over time:

• Tie documentation updates to change requests. If a developer changes the approval threshold from €5,000 to €7,500, the same ticket must include updating the rule doc — make it a checklist item in your change process, not an afterthought.
• Assign a business owner per rule, not just a developer. Developers know how the rule is implemented; the department owner knows why it exists and when it should change. Documentation without a business owner drifts.
• Review rules annually, not "someday." Put a recurring calendar reminder for each department to re-read their rules and confirm they're still accurate.
• Version the rule, don't just overwrite it. Keep a short history ("changed from €5,000 to €7,500 threshold, March 2024, approved by finance") so you can explain why the system behaves differently than it did last year.

A quick checklist before you call your documentation "done"

• Every script with an If/Case/threshold has been reviewed for hidden business logic
• Key staff have been interviewed about undocumented "tribal knowledge" rules
• Each rule is written in a consistent, scannable format (trigger, action, owner, location)
• Rules are cross-checked against what the system actually does today, not what it did at launch
• Documentation lives somewhere developers and business staff will actually find it
• A business owner (not just a developer) is assigned to each rule
• A process exists to update the doc whenever the rule itself changes

FAQ

How much time should we budget for this? For a mid-sized FileMaker system with 5-10 years of accumulated scripts, expect a first full audit to take several days to a few weeks, depending on system size — it's worth treating as its own short project rather than squeezing it into spare time.

Should every tiny rule be documented? No — focus first on rules that affect money, compliance, or customer-facing behavior. A cosmetic layout color rule matters less than a VAT calculation rule.

Who should own this documentation long-term? Ideally a business-side owner (department head) paired with the technical team, so the doc survives even if the original developer leaves.

Can AI fully automate business rule documentation? No — AI tools like Klai can accelerate drafting and flag complex logic worth reviewing, but a human still needs to confirm the rule reflects actual business intent, not just what the code happens to do.

Undocumented business rules are one of the quietest risks in any custom system — invisible until the day someone needs to change one and nobody can say for certain what it currently does. If you're staring at a FileMaker system (or any custom-built ERP) full of logic nobody wrote down, Loggix can help you audit it, document it properly, and — where it makes sense — surface those rules more clearly through a modern layout layer, an AI assistant trained on your own system, or a broader consultancy session to map out what needs fixing first.