Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 36 ยท Governance and Patterns

Naming, Documentation and Change Management

Keep dozens of Zaps, scenarios and workflows maintainable: naming conventions, step descriptions, an automation register, safe changes, versioning and a monthly review.

The first ten automations are easy to keep in your head. By the fiftieth, nobody knows why "Zap copy copy 3" exists, which one sends invoices, or what will break if you rename a column. Automations are software, even when drawn with boxes, and they need the same basics: clear names, written explanations, a record of who owns what, and a careful way to change things. This lesson gives you lightweight practices that work in Zapier, Make and n8n and cost little time.

The platform menus vary by version, so this lesson focuses on habits. Code blocks are JavaScript stand-ins: a name checker, an automation register and a change checklist you can adapt.

Naming conventions

A good name tells you what triggers it, what it does, and where at a glance. A simple pattern:

TEXT
[Area] Trigger -> Result (system)

Examples:

  • [Sales] New lead -> Route to rep (HubSpot + Slack)
  • [Finance] Paid invoice -> Receipt email
  • [Ops] Weekly 08:00 -> Report to #ops

Rules that help:

  • Start with the team or area in brackets so lists sort and filter naturally.
  • Use verbs for the result (Route, Send, Create, Sync).
  • Never use "copy", "test", "new" or "final" as the whole name. Mark experiments with a prefix like [DRAFT] or [TEST] and delete them when done.
  • Name steps too: rename "Create Row" to "Create lead row in Leads table" so Zap history is readable.
  • Use the same field names across tables and Zaps (customer_email, not email, Email and mail in different places).
JS Stand-in: check names against the convention

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Documentation people actually read

Every automation needs a short written description, kept where people will see it: in the Zap description field, in the workflow notes (n8n sticky notes, Make notes on modules), and in one shared register. Aim for five lines:

  1. Purpose: why does it exist, in one sentence.
  2. Trigger and result: what starts it, what it changes.
  3. Systems and connections: which apps, which account.
  4. Owner and backup: who is responsible.
  5. Failure plan: what happens on error, who is alerted, how to replay.

Add comments on tricky steps: "Filter: skip internal test emails (@example.com)". The reasons behind a condition are the first thing lost.

For complex flows, draw the path once. A small diagram in the shared page is worth many paragraphs:

flowchart LR
    A["Form: new lead"] --> B["Find or create contact"]
    B --> C{"Score over 70?"}
    C -- "yes" --> D["Assign to rep"]
    C -- "no" --> E["Add to nurture list"]
    D --> F["Notify in chat"]

A five-box diagram documents a Zap better than a long text.

The automation register

Keep one table (a Zapier Table, a spreadsheet or a wiki page) listing every automation: name, owner, purpose, systems, trigger, monthly volume, criticality, last reviewed. It answers questions such as "what depends on this API key?", "who owns billing automations?" and "which Zaps did not run last month?". It also drives the periodic review.

JS Stand-in: query an automation register

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Changing automations safely

Editing a live Zap that handles real customers is like editing a production website. Use a small process:

  1. Decide the change and write down the expected effect.
  2. Check dependencies: tables, other Zaps, shared connections, downstream reports. Renaming a table field breaks every step that maps it.
  3. Build in a copy: duplicate the Zap (name it [DRAFT]), keep the original running, and test the copy on test data or a test table. Turn the copy on only when it is ready, then turn the old one off (do not run both, or each event is handled twice).
  4. Version: record the change date and what changed in the description or register. Some platforms keep Zap version history you can roll back; n8n workflows can be exported as JSON and stored in Git.
  5. Watch the first runs after the change in the run history.
  6. Retire the old version after a calm period; delete or archive, never leave "OLD" Zaps running.
JS Stand-in: a pre-change checklist

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A monthly review that takes thirty minutes

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which Zap name is best?

    It names the area, the trigger, the result and the systems.
  2. 2. You built an improved copy of a live Zap. What must you do when switching?

    Two live versions would act on every event twice.
  3. 3. What is the purpose of an automation register?

    A central list makes ownership, dependencies and reviews visible.

Summary

  • Name automations and steps as [Area] Trigger -> Result (systems); keep field names consistent.
  • Document purpose, trigger and result, systems, owner and failure plan where people look; add a diagram for complex flows.
  • Keep an automation register; use it for the monthly review.
  • Change in a draft copy, switch cleanly, record the change, watch the first runs, retire the old version.

Next: Project: Lead Intake Pipeline