IntermediateLesson 12 of 305 min read

Naming, Documenting and Versioning Your Workflows

Make workflows maintainable: check names against a four-part convention, document purpose and owner and compare versions to write a changelog.

In this lesson you will

  • Name workflows with a clear pattern
  • Document purpose, owner and failure steps
  • Compare two versions to write a changelog
  • Change a live workflow safely

About 22 minutes

Which workflow sent that email?

Six months after building his first automations, Ravi gets a complaint: a customer received an order check twice. He opens his automation tool and finds a list of workflows named ‘test 2’, ‘my cool workflow (copy)’ and ‘new one final’. Which of them sent the email? Nobody knows, including Ravi. Cleverness in building is wasted if the result cannot be understood later. Naming, documenting and versioning are the habits that turn a pile of experiments into a system someone can maintain, including you, three months from now.

A naming convention

A naming convention is an agreed pattern for names, so that a list sorts and reads sensibly. A common pattern is four parts: the area of the business, the trigger, the action and a version number. For example: Sales, New email, Label and draft, v3. Each part answers a question you will ask when something goes wrong: who owns this, what starts it, what does it do and which edition is this.

Check names with a few lines of code

The program below holds eight workflow names, a few of them good and a few of them familiar. It splits each name at the bar symbol and checks that there are four parts and that the last one looks like a version, the letter v followed by digits. Printing a reason, not only a yes or no, tells you what to fix.

import re

# convention: Area | Trigger | Action | v1
names = [
    "Sales | New email | Label and draft | v3",
    "Billing | New email | Add to money list | v1",
    "Support | Form filled | Send order check | v2",
    "test 2",
    "Sales | New email | Label | version 2",
    "Junk | New email | Move to junk",
    "my cool workflow (copy)",
    "Social | Every Monday | Draft post | v1",
]
def why(name):
    parts = [p.strip() for p in name.split("|")]
    if len(parts) != 4:
        return "needs 4 parts"
    if not re.fullmatch(r"v\d+", parts[3]):
        return "bad version"
    return "ok"
bad = 0
for i, n in enumerate(names, 1):
    verdict = why(n)
    bad += verdict != "ok"
    print(f"name {i}: {verdict}")
print("valid:", len(names) - bad, "of", len(names))

# a changelog is the difference between two versions
v2 = ["new email", "classify", "label", "draft reply"]
v3 = ["new email", "redact", "classify", "label", "draft reply", "ask a person"]
added = [s for s in v3 if s not in v2]
removed = [s for s in v2 if s not in v3]
print("added:", added)
print("removed:", removed)
print("steps:", len(v2), "->", len(v3))
name 1: ok
name 2: ok
name 3: ok
name 4: needs 4 parts
name 5: bad version
name 6: needs 4 parts
name 7: needs 4 parts
name 8: ok
valid: 4 of 8
added: ['redact', 'ask a person']
removed: []
steps: 4 -> 6

Only 4 of 8 names passed. Name 5 was marked ‘bad version’: it has four parts, but its last part says ‘version 2’ instead of the short form. Name 6 was marked ‘needs 4 parts’ for a different reason: it has only three parts, so the version is missing altogether. The informal names fail for the same reason, and ‘test 2’ and ‘my cool workflow (copy)’ tell you nothing about what they do. Nobody enjoys renaming things, but doing it once, with a rule, is much cheaper than hunting for the right workflow during a problem.

Documenting what the workflow does

A name is the label on the front. Inside the workflow, add a short note covering the purpose, the owner, the data it touches and what a person should do if it fails. Four sentences are enough. Most platforms let you add notes to the workflow or to individual steps. Keep a separate list of all workflows, one line each, with its owner and whether it is switched on. When you review it each month, you will probably find a workflow nobody remembers. Switch it off before deleting it, so you can recover it if someone complains.

Versions and changelogs

Every time you change a workflow, you risk breaking something that worked. A version number and a changelog are your insurance. The second half of the program compares two versions of a workflow as lists of steps. Version 3 added redact, ask a person, and removed nothing, so the workflow grew from 4 to 6 steps. A comparison like this is the heart of a changelog entry: what was added, what was removed and why. Write the why in plain words, such as ‘added a redaction step before the AI step, after lesson 9’. If the new version misbehaves, the changelog tells you what to undo.

A safe way to change a live workflow

  1. Copy the live workflow and give the copy the next version number.
  2. Make your changes in the copy and test with sample data.
  3. Write the changelog line: what changed and why.
  4. Switch the old version off and the new one on, in that order, to avoid doing the work twice.
  5. Keep the old version for a while, switched off, in case you must go back.
Common mistake: changing the live version

Editing the live workflow directly and testing with real customers. A copy costs a minute. A broken live workflow can cost a day.

A suggestion, not a standard

The names and steps are made up. Many platforms offer their own version history or copy features, which differ by tool and plan, so check what yours provides. The convention in this lesson is a suggestion, not a standard.

Write down the names of your own workflows or tasks. Rename each to the four-part pattern, then add a one-line purpose and an owner to a simple list.

Practice for this lesson

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

Why use a naming convention?

  1. It makes workflows run faster
  2. So lists sort and read sensibly and problems can be traced
  3. It is required by every platform
  4. It removes the need for testing

Names answer who, what starts it, what it does and which edition.

What was wrong with the name that ended in “version 2”?

  1. It had too few parts
  2. It was too short
  3. The last part was not in the short v and digits form
  4. It had a bar symbol

The checker wanted v followed by digits.

What belongs in a changelog entry?

  1. What changed and why
  2. Only the date
  3. The customer list
  4. A password

The why helps you undo the right thing later.

What is a safe way to change a live workflow?

  1. Edit it live
  2. Delete it and start again
  3. Copy it, change the copy, test, then switch over
  4. Change it at night without testing

A copy lets you go back.

What should you do before deleting a workflow nobody remembers?

  1. Switch it off first, so you can recover it
  2. Delete it at once
  3. Give it to a customer
  4. Rename it test

Switching off first keeps a way back.

Summary

  • A naming convention makes problems traceable.
  • Document purpose, owner, data and what to do on failure.
  • A changelog records what changed and why.
  • Copy, test, then switch over.

Next lesson

Lesson 13 looks at schedules, polling, events and how to cope with duplicates.

Questions

Is the four-part pattern required?

No. It is a suggestion. What matters is that your names follow some pattern that you and your team understand.

How much documentation is enough?

A few sentences per workflow: purpose, owner, data touched and what to do if it fails.

Does my platform keep versions automatically?

Some do, in different ways and on some plans. Check your tool, and keep your own changelog anyway.

Progress is saved in this browser.