Documentation and handover

0:00 Documentation + handover

Here's a question every business should ask about its automations: if the person who built them left tomorrow, could anyone else fix them? Too often the answer is no. Undocumented workflows become haunted. Nobody dares touch them, and when they break, it takes days to work out why. In this lesson you'll learn what to document for every automation, naming and structure conventions, how to manage environments and changes, and a handover checklist that agencies and freelancers can use with clients.

0:35 Lesson roadmap

Here's the plan for this lesson. First, why documentation is part of the build. Then an analogy for what good documentation contains, the eleven things to document, and naming and change-control conventions. Then two examples, a one-page report doc and a full handover to a clinic in Lahore, followed by a handover checklist and the most common mistakes.

1:00 Why it matters

Why does this matter? Automations outlive their builders. Staff move on, agency contracts end, and even the original builder forgets why a filter exists six months later. For agencies and freelancers, documentation and a clean handover are also what clients remember. They're the difference between a one-off project and a trusted, long-term relationship.

1:23 Analogy: car manual + service book

An analogy. Think of a car's service book and owner's manual. The manual tells you what each control does. The service book records every change, who made it and when. And the roadside card tells you what to do when something goes wrong. Your automation documentation needs all three: a clear description of what it does, a change log, and a runbook for failures.

1:51 Document 11 things

For every automation, document eleven things. Purpose, the business outcome in a sentence or two. Owners: business, technical and a backup. The trigger, schedule, time zone and expected volume. A flow summary in plain language with a diagram. Apps and credentials, which accounts and scopes, and where credentials live. Data: what categories, where stored, retention, and which AI providers see it. AI steps: model, prompt version, schema and approval points. Error handling: retries, dead letters, alerts. A runbook. A change log. And estimated monthly costs with a cost owner.

2:30 Conventions

Conventions make large automation estates manageable. Name workflows with the team, purpose, trigger and version, like sales lead intake webform version three. Name steps by what they do, like CRM upsert contact, or AI extract lead fields. Group related workflows in folders or projects and tag environments. And store prompts and schemas as versioned text, not only inside nodes, so you can see what changed when behavior changes.

3:00 Change control

Manage changes like software. Build and test in a development copy with test credentials and sandbox data, then promote to production deliberately. n8n supports exporting workflows as JSON and, on some plans, source control. Make supports blueprint export. Zapier offers versions and change history on some plans. Keep a simple change log, and for significant changes, re-run your tests and tell stakeholders before, not after.

3:28 Example 1: one-page report doc

Example one, simple. An internal marketing team documents its weekly report workflow on one page: purpose, owner, schedule at eight forty-five Karachi time, the data sources, where the KPI calculation lives, the AI prompt version, who gets alerts, and a three-line runbook: how to pause it, how to replay a failed run, and what to check if numbers look wrong. It took thirty minutes and saved hours the first time the ads API changed.

4:00 Example 2: Lahore clinic handover

Example two, realistic. A freelancer built three n8n workflows for a clinic in Lahore: appointment reminders, review requests and a weekly report. The handover pack includes a one-page overview with a diagram, a document per workflow, and a runbook, for example: if WhatsApp messages stop, check the template status and token expiry, then replay failed executions. There's a twelve-minute recorded walkthrough. Credentials moved to the clinic's own accounts, alerts go to the clinic's operations email, and there's a paid monthly support option with a two business day response. The office manager can now pause and replay workflows confidently.

4:43 Handover checklist

Use this handover checklist. Transfer accounts and connections to client-owned service accounts. Walk through each workflow live and record it. Hand over documentation, the runbook and test data. Confirm alert recipients and the support process: who fixes what, and how fast. Remove the builder's personal access, or reduce it to the agreed support level. And set a review date, say thirty days later, to catch issues. The common mistakes: credentials tied to the builder's accounts, prompts edited in production with no history, and documentation that's just screenshots with no runbook.

5:22 Tip for agencies

A tip for agencies and freelancers: make documentation part of your price and your process, not an optional extra. Add it to your statement of work, build it as you go rather than at the end, and use the same template for every client. It makes your work look professional, reduces support calls, and makes future projects with the same client much faster, because you won't have to rediscover how you built things.

5:54 Watch me do it: document the workflow

Watch me do it. I document Crescent's n8n lead workflow using the template. Title: sales lead intake webform, version three. Purpose: route new web leads to the right owner within five minutes and acknowledge the lead. Owners: head of sales for business, ops automation for technical, agency support as backup. Trigger: webhook, about forty leads a day, Karachi time. Flow: normalize, dedupe on email, phone and domain, AI extraction, rule-based score, route, Slack plus acknowledgment email, CRM task. Apps and credentials: I list each app with the service account that connects it and its scopes. Data: names, emails, phones, company and message; no special category; execution data pruned after thirty days. AI: model tier, prompt version four with a link, schema version two, human approval before any follow-up is sent. Errors: retries on transient errors, fix queue for data errors, global error workflow. Runbook: how to pause, how to replay failed executions, how to rotate a key. Costs: estimated executions, tokens and owner. Change log with the last two versions. Then I export the workflow JSON into our repository next to the document. Finally, I ask a colleague to pause the workflow and replay a failed run using only this page. She gets stuck on where the fix queue lives, so I add the link.

7:27 Recap + try this now

Recap. Automations outlive their builders, so document purpose, owners, triggers, flow, apps, data, AI steps, errors, runbook, changes and costs. Use naming conventions, versioned prompts, dev and prod environments, and a handover checklist. Try this now: pick your most important automation and fill in the Markdown template from the lesson text. Then ask a colleague to pause it and replay a failed run using only your document. Wherever they get stuck, improve the document.

7:59 Try this now

Try this now. Pick your most important automation. Copy the Markdown template from the lesson text and fill in every section: purpose, owners, trigger, flow, apps and credentials, data, AI steps, errors, runbook, change log and costs. Then ask a colleague who didn't build it to pause the workflow and replay one failed run using only your document. Note every question they ask, and add the answers to the document.