# Documenting a validation rule so the next person understands it The formula says what a validation rule blocks. It doesn't say why. Here's how to turn it into a description someone can act on without opening the builder. **Time:** 8 minutes **What you'll have when you're done:** A one-paragraph description of a validation rule, in plain language, that explains what it checks, why it exists, and what someone should do when it fires. **Before you start:** - Any AI chat tool you're allowed to use - A validation rule you can see the formula and error message for ---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.

Next