Technical Lead & BPMN Educator·7 min read
The fear spiral
An automation builder described the problem perfectly: "It feels like a house of cards. Tiny changes upstream cause bizarre behavior downstream. Looking at code I wrote 4 months ago is like reading someone else's work."
This is the fear spiral: you build automation, it works, you move on. Months later, requirements change. You open the code. You do not remember why you built it that way. You are afraid to touch it because any change might break something you do not understand.
Why logging is not enough
Logging tells you what executed: this step ran, then this step, then this decision. But it does not tell you why it was built that way. Why is there a 3-second delay between steps? Why does this exception bypass the approval? Why is this field checked before that one?
The "why" is what you need to modify safely. Without it, every change is a gamble.
BPMN as an architectural blueprint
A BPMN diagram for each automation captures the logic visually: the flow, the decisions, the exception paths, the roles. It is the blueprint that makes the code understandable.
What to document
The process flow (tasks and sequence), decision logic (gateway conditions with the actual rules), error handling (what happens when a step fails), dependencies (which systems are called, in what order), and assumptions (field names, timing, retry expectations).
One diagram per automation
Each automation gets its own BPMN diagram. Label it with the automation name, version, and owner. Store it next to the code (same repo or linked from the README).
Annotate the fragile parts
Use BPMN text annotations to mark: "This step depends on the invoice format from Vendor X" or "Retry 3 times because the API is unreliable on Mondays." These are the hidden assumptions that cause breakage.
"I tell every developer the same thing: your future self is your most important user. A BPMN diagram next to your automation code is a gift to the person who maintains it in 6 months. That person is almost always you."
Retro-documenting existing automations
For automations already in production without documentation:
- 1.Start with the trigger. What starts this automation? A scheduled job? An incoming message? A user action?
- 2.Trace the happy path from logs. What steps executed in the most common run? Map those first.
- 3.Add decisions and exceptions from the code. Where are the if/else branches? What happens on errors?
- 4.Annotate the fragile assumptions. Every hardcoded value, timing dependency, and external system call.
Related guides
Keep learning
Frequently asked questions
Should I document automations before or after building them?▼
Before is ideal - the diagram becomes the specification. But for existing automations, retro-documenting is valuable too. Start with the automations that change most often or are most fragile.
Can I generate BPMN from existing automation code?▼
Some process engines (Camunda, Flowable) store the BPMN natively. For custom code, you need to reverse-engineer the logic into a diagram. AI tools can help generate a first draft from code descriptions.
How detailed should automation documentation be?▼
Every decision point, every external system call, every error handling path. The goal is that someone who did not build the automation can understand it well enough to modify it safely.