Key takeaways
- We run a lot of automations. For a while the only person who knew how any of them worked was the person who built them.
- Now every one has a written entry answering the same seven questions, and an automation is not finished until its entry exists.
- The seven questions are deliberately boring, and two of them are the ones people always skip.
- It lives as an internal course, so onboarding a teammate is one tag instead of one long call.
- The hardest rule to keep is that the document gets updated in the same sitting as the change. Not later.
We have around 140 automations running this business. Forms that create contacts, workflows that send follow ups, AI agents answering the phone, scheduled jobs that build content overnight, scripts that watch the other scripts.
Every one of them made sense the day it was built. That is the trap. Something obvious in the moment becomes completely opaque four months later, and the only copy of the explanation lives in one person's head.
We noticed the real cost when it was time to bring someone else in. Onboarding was going to be a series of long calls where the answer to almost every question was "let me remember how that one works."
Seven questions, every time
The fix was a shape. Every automation answers the same seven questions, in the same order:
- Where does it run. Which system actually executes this. A workflow in the CRM, a scheduled job on the machine, a function on the website.
- What triggers it. The event or the time.
- What does it do. The actual steps, in order.
- What does a human still do. Often nothing. Sometimes something critical.
- Where does its brain live. Which file or record holds the state it reads and writes.
- How do you tell it ran, or failed. The observable signal.
- Gotchas. The thing that will bite the next person.
The two that people skip are numbers four and six, and they are the two that matter most when something goes wrong at 4pm on a Friday.
"What does a human still do" is the one that prevents the worst kind of failure. An automation that is 90 percent hands off gets remembered as fully hands off, and the last 10 percent stops happening. Six weeks later you find a queue of work nobody was ever going to touch, because everyone believed the robot had it.
"How do you tell it ran or failed" is the one that turns a mystery into a five minute check. The honest answer is sometimes uncomfortable. For a few of ours the answer is that a run doing nothing and a run being blocked look identical from the outside, which is a real weakness written down as a real weakness.
Writing them down changed what we built
This was the part we did not expect. Filling in seven fields for every automation surfaced problems that nobody would have gone looking for.
Two automations turned out to create the same contact from the same form by two different routes, which is fine until you are debugging a duplicate and do not know both paths exist. One had a note attached saying it still needs to be pointed at a different AI agent, an open item that had been invisible because it lived in nobody's list. Another turned out to share a trigger form with a completely separate sequence, so one submission quietly started two.
None of those are bugs exactly. They are the kind of overlap that accumulates when things get built one at a time by someone moving fast. You only see them when you write every automation down in the same shape and read them side by side.
Access is one tag
The whole thing lives as an internal course in our CRM, organised into chapters by area. Lead intake. Nurture. Sales. Client care. Content. The phones. Prospecting. Internal ops. Meetings. Hiring.
Granting someone access is a single tag on their contact record. Tag them, an automation grants the course, they are in. No account setup, no sharing links, no permissions conversation.
That matters more than it sounds. Every extra step between "we hired someone" and "they can read how this works" is a step that gets skipped on a busy week.
The rule that makes it stick
The discipline is the only part that is hard: an automation is not shipped until its entry exists. It gets written in the same sitting as the automation, not in a cleanup pass three weeks later.
We are honest about why. Documentation written later is documentation written from memory, and memory is where the gotchas go to die. The thing you would warn the next person about is vividly clear for about a day after you fight it, and gone in a week.
We also learned to be careful about a smaller thing. Our own summary of this system said 130 entries across 13 chapters. The actual file has 140 entries across 11. Nobody lied. The number was true when it was written and the file kept growing. It is a small reminder that a count in a summary ages badly, and the file always wins.
What this means for a business in San Jose
If you have any marketing automation San Jose setup at all, even three workflows, you already have this problem in miniature. The question worth asking is not "is it documented" but "could someone else keep it running if I were out for two weeks."
You do not need a course. Start with a single page and those seven headings. Fill it in for the automation you would least like to break. That is usually the one connected to money or to a customer waiting on a reply.
Then make the rule real: nothing new ships without its entry. It costs about ten minutes per automation at the time and saves a lot more than that the first time something breaks while you are on holiday.
We did not write all this down to be tidy. We wrote it down so the business stops living in one person's head.
If you want automations built with the explanation included, that is how we work. Have a look at optechsol.llc.