The automation that helped you the most last quarter is probably the one most likely to break your team next quarter. The person who built it knows what it does, where the failure points are, and how to unstick it. When they leave (or just move on to another project), what they leave behind is a black box that runs until it doesn't.
The fix isn't a heroic effort to document everything in retrospect. It's a small set of habits applied during the build, so the automation arrives in production already legible to the next person. Six habits, in order of impact.
1. Name everything like a stranger will read it
The lazy default is “Lead Sync”, “Webhook Receiver”, “Daily Job”. The next maintainer opens the workspace and has to click into each one to find out what it does.
Good names answer three questions without opening the workflow:
- What triggers it (webhook, schedule, manual)
- What it does (sync, transform, alert)
- Which systems it touches (HubSpot → Slack, Asana → Snowflake)
Examples that work: webhook · HubSpot lead → Slack alert, nightly · Asana tasks → Snowflake warehouse sync. Verbose? Yes. Worth it the first time someone new scans the workspace? Absolutely.
2. Write a README, not in a wiki
Every automation should have a README that lives withthe automation, not on a separate wiki page that drifts. Most platforms support a description field on the workflow itself; use it. Failing that, a Notion/Confluence page linked from the workflow name works — but the link goes both ways or it's useless.
A 5-line README beats a 200-line one. Cover:
- What this automation does, in plain English
- Why it exists (what the manual version would look like)
- What systems it touches and what credentials it uses
- What the most likely failure mode is and how to recover
- Who currently owns it
That last line is the most important. If “owner” is blank, the automation will eventually die without a coroner.
3. Treat credentials like infrastructure, not personal
The single biggest reason automations fail when someone leaves: the OAuth tokens were issued under their personal account. When the account is deactivated, the tokens revoke and the workflow stops without warning.
Establish a service-account pattern early. For each system (HubSpot, Asana, Slack, Salesforce), create a dedicatedautomation@yourcompany-style account with the narrowest permissions the workflow needs. Re-authorise every automation through that account during a quiet week before the first wave of departures. Future-you will be relieved.
4. Build failure visibility before you celebrate
An automation that fails silently is worse than no automation — it's a quiet liability that nobody notices until a customer does. Before shipping, build:
- Alerts when a run fails.Slack message, email digest, ticket created — the channel doesn't matter, just that a human sees it within the working day.
- A dead-letter pattern.Failed events shouldn't evaporate. Park them somewhere a human can inspect and retry.
- A heartbeat. For scheduled jobs, an alert when the run does nothappen. “Job didn't run today” is the failure that's easiest to miss.
5. Tag every step with a comment, every time
Most automation platforms (Make, n8n, Zapier, Workato) support per-step notes or sticky comments. Use them. A one-line note explaining why a step exists is the single most valuable documentation you can leave for the next maintainer.
Examples that pay back:
// HubSpot returns null for lifecycle_stage if the contact is new — default to ‘lead’// We poll every 5min instead of webhook because their webhook fires before the record is fully written// Yes, this looks redundant — needed because the downstream API doesn't handle empty arrays
These comments save the next person from rediscovering the same edge cases via production incidents.
6. Schedule a quarterly tune-up
Automations rot. APIs deprecate fields. Business rules change. Schemas drift. The only practical defence is a recurring review.
Once a quarter, the owner does a 30-minute pass per automation:
- Has anything failed silently in the last 90 days?
- Does the README still describe what the automation does?
- Are any of the credentials about to expire?
- Is the workflow still solving a real problem? (Some don't.)
Put the review on a recurring calendar invite. If it's someone's job, it gets done; if it's everyone's job, it gets done by no one.
The handover that goes well
When someone leaves a role that owns automations, a clean handover looks like this:
- Walk through every active automation with the new owner. 30 minutes max per automation. The names + READMEs should make this fast.
- Re-authorise anything tied to the departing person's account using the service-account pattern.
- Update the owner fieldin the README and in your workspace's audit log.
- Run a tune-upwith the new owner before they take responsibility, so they've touched each workflow at least once.
The whole process takes a day for a team with twenty automations. Without the six habits above, the equivalent handover takes weeks of detective work — or, more often, doesn't happen, and the new owner discovers each automation when it breaks.
The honest test
Pick one of your team's automations. Ask: if its creator left tomorrow, could someone else explain what it does, fix it when it breaks, and decide when to retire it? If yes, you've invested in durability. If no, today is a good day to start.