How to document an automation

Your invoicing script has been quietly running for three years. It was built by a developer who left the company eighteen months ago. Last week it started skipping every fifth invoice, and nobody in the building knows why it exists, what it touches, or how to safely change it.

This is the single most common failure mode in automated business processes: the automation works fine right up until someone needs to understand it, and then it becomes a black box that everyone is afraid to touch. This article gives you a concrete method for documenting any automation — a FileMaker script, an API connector, a scheduled ERP job, an AI-assisted workflow — so that it stays maintainable long after the person who built it has moved on.

Why does undocumented automation become a business risk?

An automation is code and configuration that runs without a human watching it in real time. That's exactly what makes it dangerous when nobody has written down what it does.

Concretely, this is what goes wrong without documentation:

• A FileMaker script triggered on record commit silently updates stock levels. A new developer adds a second trigger on the same event, not realizing the first one exists, and now stock gets adjusted twice.
• An API connector pulls orders from a webshop into the ERP every 15 minutes. The webshop changes its API response format in a minor update. Orders stop flowing in, but because no one documented which endpoint fields the connector depends on, it takes two days to find the cause.
• A finance manager asks "why does this discount always get applied on Tuesdays?" and nobody currently employed can answer, because the business rule lived only in one developer's head.

Each of these is not a hypothetical edge case — it's the normal lifecycle of automation in a growing company. The parent article on how to automate business processes without losing control makes the broader case that control, not just automation itself, is what protects a business as it scales. Documentation is the concrete mechanism that gives you that control: it's how you keep an automation auditable, transferable, and safe to change.

What should you actually document about an automation?

Good automation documentation answers five questions for someone who has never seen the process before. Skipping any one of them is what usually causes the 2 a.m. "why did this break" phone call.

1. Trigger — what starts it? A button click, a scheduled server script, a webhook, a record being created or modified, an email arriving.
2. Purpose — what business problem does it solve, in plain language? Not "updates table X" but "prevents double-booking of technicians by locking the calendar slot before the confirmation email goes out."
3. Data touched — which tables, fields, files, or external systems does it read from and write to? This is the part developers skip most often, and it's the part that matters most during an audit or a migration.
4. Dependencies — what does it assume is true to run correctly? Example: "assumes the customer record already has a VAT number filled in" or "assumes the Exact Online API token has not expired."
5. Failure behavior — what happens if it fails halfway through? Does it roll back, log an error, send a notification, or silently do nothing? This is the single most important question for anything touching money, inventory, or customer communication.

If you can answer those five questions for every automation in your system, you already have better documentation than most companies with a decade-old FileMaker or ERP setup.

How do you document a FileMaker script step by step?

FileMaker makes this easier than most platforms because the script itself is partly self-documenting — but only if you use the features deliberately.

1. Name scripts by business intent, not technical action. "Update Invoice Status" tells you nothing. "Mark Invoice Paid and Notify Sales Rep" tells you what it's for.
2. Use script comment steps at the top of every script. Write a short header: what triggers it, what it changes, who owns it, and the date it was last modified. This costs thirty seconds and saves hours.
3. Group related scripts into folders in the Script Workspace so the structure of the automation is visible at a glance, not buried in a flat alphabetical list of 200 scripts.
4. Document script parameters and script results explicitly — a script that receives a parameter with no comment explaining its expected format will be misused by the next developer within a year.
5. Keep a separate change log outside the file (a shared doc, a wiki page, or a lightweight tool) for anything that isn't obvious from reading the script itself — business context, exceptions, and "do not touch this without checking with finance" warnings.
6. Record where AI fits in, if it does. If a script calls out to an AI model — for example using something like Klai to classify incoming emails or extract data from a PDF before a FileMaker script processes it — document exactly what prompt or model is used, what output format is expected, and what happens if the AI returns something unexpected. AI steps fail differently than deterministic code: they degrade gracefully or return confidently wrong answers, and your documentation needs to say what your automation does in that case.

What about documenting the interface, not just the logic?

Automation documentation usually focuses on scripts and data flow, but the interface a user interacts with is part of the automation too — and it's often the least documented layer.

If part of your automation includes a form a user fills in before a process runs — for example, an intake form built with something like FMBetterForms that triggers a downstream FileMaker workflow once submitted — document:

• Which fields are required versus optional, and why.
• What validation happens client-side versus what validation happens later in the script.
• What happens to a submission that fails validation — is it saved as a draft, discarded, or flagged for review?

This matters because interface changes are exactly the kind of small, "harmless-looking" edit that breaks an automation downstream. Someone makes a field optional in the form without realizing three scripts later assume it's always filled in.

How much documentation is enough — and when is it overkill?

Not every automation deserves the same depth of documentation. A reasonable rule of thumb:

• High-risk automations (touch money, inventory, contracts, customer-facing communication, or run unattended on a schedule): full five-question documentation, kept up to date, reviewed whenever the script changes.
• Medium-risk automations (internal convenience scripts, reporting, notifications): a short header comment plus a one-paragraph entry in a shared log is enough.
• Low-risk automations (simple UI shortcuts, layout navigation scripts): the script name and a one-line comment usually suffices.

Over-documenting low-risk scripts wastes time that could go toward documenting the handful of automations that would actually cause a crisis if they broke silently.

A practical checklist for documenting any automation

Use this before you consider an automation "done":

• Does the automation have a name that describes its business purpose, not just its technical action?
• Is the trigger (what starts it, and how often) written down somewhere outside the developer's memory?
• Are all tables, fields, files, and external systems it touches listed?
• Are its assumptions and dependencies explicit (data that must already exist, tokens that must be valid, prior steps that must have run)?
• Is its failure behavior defined and, ideally, tested — does it log, notify, or roll back?
• If AI is involved anywhere in the chain, is the expected input/output and fallback behavior documented?
• Is there a single place (wiki, shared doc, or in-file comments) where a new developer or IT manager could find all of this without asking around?
• Has someone who did not build the automation tried to read the documentation and confirmed they understand it?

That last item is the real test. Documentation that only makes sense to the person who wrote it isn't documentation — it's a memory aid.

FAQ: documenting business automations

Do I need special software to document automations? No. A shared wiki page, a well-organized folder of markdown files, or even structured comments inside the FileMaker file itself are all sufficient starting points. The tool matters far less than the habit of keeping documentation current.

Who should own automation documentation — the developer or the business owner? Both, for different layers. The developer documents the technical trigger, data flow, and failure behavior. The business owner or process owner documents the why: what business rule this automation enforces, and what happens if it's turned off.

How often should documentation be reviewed? Any time the automation's logic changes, and at minimum once a year for anything high-risk, even if nothing changed — this catches documentation that has silently drifted out of sync with reality.

What's the biggest mistake companies make when documenting automations? Writing the documentation once at launch and never updating it again. Stale documentation that describes an old version of the automation is often worse than no documentation, because it actively misleads the next person who reads it.

Where does this leave you?

Documentation is not a bureaucratic afterthought — it's what turns an automation from a fragile, person-dependent trick into a durable business asset that survives staff changes, audits, and growth. If you're auditing a FileMaker system, an ERP customization, or a set of API connectors that nobody fully trusts anymore, Loggix can help map out what each automation actually does, document it properly, and — where it makes sense — rebuild the riskiest parts as a more transparent custom FileMaker solution, a tailored web application, or a cleanly documented API integration. Sometimes that also means adding AI tools thoughtfully rather than as an opaque add-on, or simply sitting down together to map out where control has quietly slipped out of the process.