By Brooke Houck, PhD · Last updated: August 25, 2026
Most automation handoffs fail quietly. The workflow keeps running for months, then something upstream changes — an API field gets renamed, a spreadsheet gets restructured, someone leaves the company — and the client has no idea where to start, because the only documentation that ever existed was in the builder's head. A handoff document is supposed to prevent that. Here's what actually needs to be in one, based on where I've seen handoffs go wrong.
Before anything technical, write the plain-language summary a non-technical stakeholder would actually read: what problem this automation solves, what triggers it, and what happens as a result. If the only description of the workflow is its node names, you haven't documented it — you've just transcribed it. A client should be able to read this paragraph and describe the automation correctly to their own boss without opening the tool it runs in.
State the trigger explicitly and concretely: a schedule (and what time zone it runs in), a webhook, a form submission, a new row in a sheet, an email arriving. Include the practical detail people forget — how often it actually fires, whether it can fire more than once for the same event, and what happens if it fires and finds nothing to do. "Runs when a new lead comes in" is not the same information as "polls the CRM every 15 minutes for records tagged 'new'."
Walk through what happens between the trigger and the result, in the order it happens, in sentences a client can follow — not a screenshot of the canvas. A diagram of the flow is useful alongside this, but it's not a substitute for it; diagrams show structure, not what each step is actually doing or why. Group tightly related technical steps into one plain-language beat rather than documenting every node 1:1 — the goal is comprehension, not a literal transcript of the build.
List the values the automation depends on — API endpoints, spreadsheet IDs, email addresses it sends to or from, field names it reads — and where each one is configured, so a future editor doesn't have to hunt through every node to find what needs updating when something changes. This is the single most common cause of "it broke and nobody could fix it": the person trying to fix it can't find where the broken value actually lives.
Name which accounts and credential types the automation depends on — "a Google Workspace service account with Sheets and Gmail scopes," "a Stripe restricted API key," "an OAuth connection to the client's own CRM" — and who owns each one. Never put an actual key, token, or password in the document itself; that's what a password manager or the platform's own credential store is for. What the document needs to answer is "if this credential expires or gets revoked, whose account is it, and what needs to be reconnected."
Document the failure behavior, not just the happy path: does the automation retry automatically, does it notify anyone, does it fail silently, does a partial run leave anything in an inconsistent state (a duplicate row, a half-sent email). If there's error-handling logic in the build, explain what it's actually for in plain language. If there isn't any, say that plainly too — a client who knows an automation has no error handling can watch for problems; a client who assumes it's handled won't.
State plainly who is responsible for the automation after handoff — the client's own team, the agency on a support retainer, or no one — and what "support" actually covers if it's ongoing. Ambiguity here is where most disputes start: the client assumes the builder is still watching it, the builder assumes the client took over, and nobody notices until it's been broken for three weeks.
Note which parts are safe for a non-builder to adjust (a schedule time, an email template's wording) versus which parts require someone who can edit the workflow logic itself, and roughly what it would take to make a small change versus a structural one. This sets realistic expectations before the client asks for "just a quick tweak" that turns out not to be quick.
Start one at handoff, even if it's just one line: what shipped and when. Every automation gets modified eventually, and a document that was accurate at handoff but never updated again becomes actively misleading within a year. A changelog is what tells a future editor whether the document in front of them still describes what's actually running.
Skip anything that only makes sense to someone who already knows the tool: internal node IDs, the build platform's UI terminology, implementation details that don't change what the client needs to know or do. A handoff document is for the person receiving the automation, not a build log for other automation builders. If a client has to ask what a "node" is to understand their own documentation, it's written for the wrong audience.