The Documentation Standard That Makes an Automation Yours to Keep

Most automation handoffs leave you renting the workflow. The builder finishes, sends a Loom video, maybe a Notion page with screenshots, and disappears. Six months later something breaks, the API changes, or you want to add a step — and you're back paying someone to touch a system you supposedly own.

The difference between owning an automation and renting it is documentation. Not the kind of documentation builders write to prove they did the work. The kind operators need to run, fix, and change the system without the builder in the room.

The operator needs different things than the builder left behind

When a builder finishes a workflow, what's in their head is the architecture: which nodes connect to which, why they chose a webhook over a polling trigger, what the data shape looks like coming out of step four. That's builder knowledge. It's almost useless to an operator.

An operator — the person on your team who actually has to live with this thing — needs to answer three questions on a Tuesday morning when something goes sideways:

Is it running like it should be?

If not, where did it break and what do I do?

If the business changes, can I adjust it or do I need to call someone?

Most handoff docs answer none of these. They explain how the workflow was built, not how it's run. That's the entire problem.

A good test: hand the documentation to someone on your team who didn't commission the project. Give them no other context. Can they tell you, in fifteen minutes, what this automation does for the business, how to confirm it ran today, and what to do if it didn't? If not, the docs are decoration.

The three documents that actually matter

Every automation we ship at Catalyst comes with three documents. Not three sections of one document — three separate documents, because they get used in different moments by different people.

The Run Doc. This is the shortest one. It answers: what does this thing do, when does it run, how do I know it worked, and where does the output live. It should fit on one screen. It includes a plain-English description of the trigger ('Every time a new lead form is submitted on the contact page'), the outcome ('A row is added to the Leads sheet and a Slack message is posted to #sales'), and the success signal ('You should see a green check in the run history within 30 seconds of submission'). No node diagrams. No API references. If your office manager can read it and explain the workflow to your accountant, it's done.

The Fix Doc. This is the one you'll actually use. It's structured as a list of failure modes, each with a symptom, a likely cause, and a specific action. 'Symptom: Slack message didn't post but the sheet updated. Cause: Slack token expired (happens roughly every 90 days). Action: Go to Settings > Integrations > Slack, click Reconnect, re-authorize. Test by submitting a dummy form.' Each entry should name the exact screens, buttons, and accounts involved. Vague advice like 'check the logs' is not a fix doc — that's the builder waving from the shore. Include at minimum: every external service that could expire credentials, every step where data shape matters, and any rate limits you're operating near.

The Change Doc. This is the one builders forget entirely. It answers: what's reasonable for the operator to change themselves, what requires a developer, and how to make the safe changes without breaking things. Common safe changes: adding a recipient to a notification, changing the wording of an email template, adjusting a threshold value, pausing the workflow for a holiday. Each one gets a short procedure. Common unsafe changes — adding a new branch, changing the trigger, swapping a destination service — are explicitly listed as 'call your developer.' This boundary is what makes ownership real. Without it, every change is scary and every change becomes a billable hour.

What goes in each, concretely

For a workflow that takes inbound leads, scores them with an LLM, and routes them to the right salesperson, here's what the three docs look like in practice.

The Run Doc is six lines. Trigger: new submission on /contact form. Action: lead gets scored 1-5 by the model, written to the CRM, and assigned to a rep based on territory. Schedule: real-time, 24/7. Success signal: new row in the 'Scored Leads' view within 60 seconds. Failure signal: alert in #ops-alerts. Owner: Sarah.

The Fix Doc has maybe a dozen entries. The first three are always the most common failures — usually expired tokens, schema drift on the source side, or rate limits. The remaining nine cover the long tail. Each one is a self-contained recipe an operator can follow without judgment calls.

The Change Doc has a 'you can do this' column and a 'we need to do this' column. Adding a new sales rep to the territory router? Operator change, here's the four-step procedure. Changing how leads are scored? Developer change, because the prompt and the scoring logic are tested together. The point isn't to gatekeep — it's to be honest about where the safe edges are.

Test the docs by handing them to someone else

The only valid quality check for documentation is a stranger using it successfully. Not the builder reading their own work. Not the project sponsor nodding politely.

Before we close out an engagement, we run what we call a cold handoff. Someone on the client's team who wasn't involved in the build gets the three docs and a list of tasks: confirm yesterday's runs, simulate a token expiration and recover from it, add a new recipient to a notification. If they can do all three without asking questions, the documentation is shippable. If they get stuck, we revise — not by explaining it to them, but by fixing the document so the next person doesn't get stuck.

This is the part most builders skip because it's uncomfortable. It exposes every place where you assumed knowledge the operator doesn't have. It's also the single highest-leverage thing you can do to make an automation actually owned by the business that paid for it.

What this costs and why it's worth it

Proper documentation adds roughly 15-25% to the build time of a workflow. It's the least glamorous part of the work. It's also the part that determines whether, two years from now, you have a system that earns its keep or a black box you're afraid to touch.

We've inherited enough other people's automations to know which one is more common. The ones with real docs get extended, adapted, and kept. The ones without get quietly turned off when the first thing breaks, and the business goes back to doing the work manually — with the added insult of having paid for the failed automation.

If you're commissioning an automation, make the three docs a deliverable in the contract. If you're inheriting one without them, that's the first project: write the Run, Fix, and Change docs yourself, using the existing system as the source of truth. It's tedious. It's also how you take ownership of something you only nominally own today.

If you want to see what this standard looks like applied to your stack, our process walks through how we structure handoffs so the automation stays yours after we leave.