Documenting a validation rule so the next person understands it

A validation rule blocks a save with an error message and a formula, and neither one tells you why the rule exists. Six months later someone hits it, doesn’t understand it, and either files a ticket or works around it by changing an unrelated field until the error goes away. Both cost more time than writing the rule down once would have.

---

What you’re actually documenting

Three separate things, and a good description keeps them separate:

1. What the formula checks. The literal condition, translated out of Salesforce syntax.
2. Why it exists. The business rule or edge case someone was protecting against. This is usually not written anywhere and has to be reconstructed.
3. What to do when it fires. The fix from the user’s side, not the admin’s.

Most validation rule documentation, when it exists at all, only covers the first one.

---

Step 1: give it the formula and the error message, together

Object: [e.g. Opportunity]
Validation rule formula:
[paste the exact formula]

Error message shown to the user:
[paste it exactly as it appears]

Error location: [record-level banner, or a specific field]

Translate this formula into plain English. State the exact condition that
blocks the save, in one or two sentences a non-technical user could read.
Don't guess at intent yet, just the logic.

Ask for the translation on its own first. A formula with nested AND/OR or a ISPICKVAL check against several values is exactly where a fast read gets the logic backwards, and it’s cheaper to catch that now than after the intent has been layered on top of a wrong reading.

---

Step 2: verify the translation against a real record

Before trusting the plain-English version, test it. Either pull up a record you know should pass and one you know should fail, or build two fake ones with the shape from your sample-data guide if the real records aren’t something you can paste in.

If the plain-English description doesn’t correctly predict which record fails, the formula reading was wrong. Go back to step 1 with the specific mismatch named, rather than asking for a general re-check.

---

Step 3: reconstruct the why

This is the part a formula can’t answer on its own, so treat the AI’s answer as a hypothesis, not a fact.

Given this validation rule and what it checks: [paste your verified
translation]

What business problem would a rule like this typically prevent?
Give me two or three plausible reasons, not one confident guess.

Pick the reason that matches what you actually know about the process, or go ask whoever built it. Writing down a plausible-sounding but wrong reason is worse than leaving the field blank, because the next person will trust it.

---

Step 4: write the description for the person who hits the error

Write a two-to-three sentence description combining:
1. What triggers this error, in plain language
2. Why the rule exists: [paste the reason you settled on]
3. What the user should do differently to pass

Audience: someone who has never seen this rule before and just
hit the error message.

Put this somewhere it’ll actually be found: a description field on the rule itself, a shared doc linked from there, or wherever your team keeps this kind of note. A perfect description nobody can find helps nobody.

---

When it breaks

The formula translation and the actual behavior disagree on an edge case. Formulas with date logic, blank-field checks, or record type conditions are the most common place this happens. Test more records at the boundary, not just one obvious pass and one obvious fail.

Nobody can confirm which reason from step 3 is correct. Say so in the description rather than picking one to sound complete: “Reason unconfirmed, likely protects against [X]” is more useful six months from now than a fabricated certainty.

The rule turns out to have no clear reason anymore. Some validation rules outlive the process they were built for. That’s worth flagging to whoever owns the object, not documenting as if it’s still load-bearing.

The formula is too complex to translate in one pass. Break it at each top-level AND/OR and translate the pieces separately before combining them. A formula you can’t summarize in two sentences once broken apart is a sign the rule itself may be doing too much.

---

What to try next

The same four steps work for a required-field rule, a duplicate rule, or a process built into automation instead of a formula. The specifics change; translating logic, verifying it, reconstructing intent, writing for the person who hits it, doesn’t.