How to document your life and work workflows like you actually want to find them later

I didn’t document anything for the first three years I was freelancing. Everything just lived in my brain, on scattered post-it notes, or inside obscure little automations that had ridiculous names like “Zap step 23 FIXED_USE_THIS_ONE_FINAL.” I finally broke down after a combination of a corrupted Notion template and a dead webhook killed half a client reporting flow right before a weekly check-in. I couldn’t even tell what the original process *was* supposed to do 🙃

If you’re running your work and personal life through tools like Zapier, Notion, Airtable, and Google Sheets, but don’t have a system for keeping track of why any of it exists or how it works, welcome. Let’s talk about how I started documenting things in a way that makes sense even six months later.

1. Decide where your workflows actually live

Okay, this sounds obvious, but it isn’t. You’ll probably think, “Well, the workflows live *in* Zapier or Notion.” But that’s not the same as saying where the *documentation* of them should live.

Right now, my actual setups span across Zapier, Make, a few Google Apps Scripts, plus a handful of rogue Shortcuts automations on my phone. If I have to navigate to each tool just to understand what’s wired up, I’m never going to do it. So I had to pick one place for documentation — a central nervous system. For me, that became Notion, even though I really wanted it to be Obsidian at one point (hot take: Obsidian is amazing for writing and scratchpad thinking, but it just didn’t hold up for referencing dynamic workflows quickly).

At one point, I tried documenting workflows directly inside Zap descriptions. That worked for simple 2-step automations. But when you have a 12-step Zap with multiple paths and filters and a looping webhook that sometimes just… doesn’t trigger?… writing documentation within the description box was just pain. Literal pain.

So now every automation, no matter where it lives, gets a structured Notion entry with these parts:

• Workflow name (and a slug I can search from the command palette)
• Plain English summary of what it’s supposed to do
• Tool stack involved (like, “Zapier + Airtable + Gmail”)
• Link to the live Zap or script
• Date of last successful change + a field I manually update when I break it on accident 😅
• A dumb little diagram made in Excalidraw if the flow is complicated

I’ll sometimes screenshot the Zap if it’s over 8 steps long or has multiple filter branches, because man, Zapier’s UI hides stuff so aggressively after about five steps.

2. Write what happens when it fails not only when it works

I used to log only the happy path. Like, “Trigger: New Airtable record → Action: Send email → Done!” But most of the actual debugging I’ve had to do comes from failures. The Airtable view broke. The label filter didn’t match. Someone deleted the webhook token (me. always me).

Now the bottom of every workflow doc includes a section called “What it breaks when it breaks.” Don’t worry, I cried typing that once too 🙂

A few useful patterns I do here:

• If a Zap silently fails (i.e., shows no red ‘X’, but still doesn’t fully trigger an action), I document the trigger + filter mismatch
• I include error messages *as they appear*, like:

    400 Bad Request: Error parsing line_item_id. Expected string but got null
  

• I paste obfuscated curl commands if testing trigger endpoints
• I note which tool’s support actually helped, if any (spoiler: Webflow’s support ghosted me twice, while Make’s support solved a webhook problem by literally reproducing my build?)

And honestly? Sometimes I write things like: “If this tie-breaks between two filters, it’s random and there’s no way to force it.” That’s useful context for future me.

Here’s a real one: I had a Google Sheet → Apps Script → Slack DM workflow that just *stopped* sending unprompted. I spent half an hour debugging before I realized I had hit the daily quota limit — but Apps Script only surfaces that error in the logs, not the UI. So I wrote: “Check Executions > Logs for ‘Exceeded daily quota’ if Slack message doesn’t go out.”

3. Version control has to be built in somewhere

You’d think Zapier would let you version workflows. It kind of does! You get auto-saved drafts when editing, but only one at a time per Zap. And once you turn on the Zap, poof. Draft gone. Not helpful.

I added a field in Notion for version notes. Every time I change something non-trivial, I manually type what I changed. Is this extra work? Yeah. But it takes like 20 seconds and has saved my *** at least three times when I forgot why something’s different now.

What I want is git for workflows. What I have is a field that says:

• 2024-04-03: Changed email parsing field to “customer_email_cleaned” because the original was occasionally blank due to upstream form bug.
• 2024-04-14: Disabled Slack DM step after complaint from user who didn’t want DMs anymore 😭

Also, if you use Apps Script or Shell scripts, put everything in GitHub or Bitbucket even if you’re the only user. I once lost a critical script because I hadn’t copied the project to another Google account before the original account got deactivated. Docs were intact. Script, gone.

4. Connect workflows to the actual outcomes you care about

Here’s what I mean by this. Let’s say you have a flow that updates a CRM record when someone books a Calendly event. Cool. But why does that matter? Three months later, I will forget if it exists to segment leads, track response times, or trigger booking bonuses.

So under each Notion entry I now include a really short section called:

→ “Why I care if this works”

It always includes something *real*, not abstract. Like:

• I want to make sure new contacts are segmented as high-priority if they come from Podcast interviews (Calendly booking has metadata source)
• This Zap drives my ability to follow up with qualified leads in under 2 hours without checking inbox manually
• I get free credits from this tool if I complete X activities — this logs those activities

If I can’t write anything here, the automation might be unnecessary. That has saved me from hoarding Zaps that once made sense but now just add chaos.

Also, try pulling in real stats. For one flow, I added “As of last check, this auto-reply catches 9 out of 10 consultant inquiries.” Now I know if the success rate drops significantly, something broke.

5. Allow chaos in alternate drafts and duplicates

I still have random extra Zaps called things like “Try 2 w FILTER” and “Copy of TEST WORKING?” That’s fine. The important mindset shift was this:

→ Clean flows = documented and used

→ Junk experiments = kept separate and labeled

Trying to force yourself to always have clean Zapier setups just slows you down. Sometimes I need to try three versions of a formatter step before the date comes out right. I just copy the whole Zap and work in the dupe. If it works, *then* I go update the master flow and the Notion doc.

Bonus trick: I color-code Zaps now. Orange = live. Yellow = in-testing. Grey = deprecated. This isn’t built into Zapier — I just prepend the name with a colored dot emoji :). If the 💛 one works, promote it to 🟧.

Also, Notion has this weird sync bug where if I duplicate a database item too many times quickly (honestly not *that* quickly), some of the new entries have their internal IDs stuck — meaning clicking on links jumps to the wrong record. This seems to happen if I hit CMD+D like five times fast during a doc sprint. So now I just slow down and wait a few seconds between duplicates (yes, I hate it too ¯\_(ツ)_/¯).

6. Encourage future you to actually refer back

I had to write myself a little SOP for when something breaks. It literally says:

1. Search Notion for the flow name
2. Check if there’s a known issue described
3. ONLY THEN log into Zapier or Make

This has actually helped me avoid going straight into panic-fueled editing mode. I also linked a shortcut in my Raycast bar to pull up all entries tagged “automation,” so I can filter by tool.

One obscure but helpful trick: if you use Arc browser, make your automation doc dashboard a pinned tab with “Little Arc” enabled, so it stays open but doesn’t clutter your window counts. Trust me.

Also, every time I solve something weird, I paste the solution at the top of the doc in bold with the tag ✅ FIXED. That way, scanning a row in database view shows me at a glance which ones had issues that are now resolved. It’s an emotional thing more than a systems thing. I just need to believe some of these are solved.

Like, the webhook that was firing twice? Turned out to be because Make was still listening on a previously archived route. Nothing in the UI showed that was the case. I only figured it out because I documented the time of the duplicate requests separately. So yeah, maybe I’m overly detailed now. Or maybe next week me is going to be very grateful.