I almost shipped an n8n workflow with no documentation. It ran perfectly, so why bother?
Then I imagined someone opening it in six months with no idea why any of it was built the way it was. So I stopped and asked myself what they'd actually need.
The harder question was whether someone else could understand it. Maybe this is the technical writer in me, but I started looking past the workflow itself. If I handed this over to another developer tomorrow, would they understand why each decision existed, or would they have to piece it together node by node?
It looks simple enough
The workflow itself isn't particularly complicated. A new invoice comes in, the workflow checks whether approval is needed, routes it to the right person on Slack, waits for a decision, and updates the final status.
On the canvas, everything looks obvious.
That's exactly the problem. The canvas tells you what happens. It doesn't tell you why each decision exists or what assumptions the workflow depends on.
What the workflow doesn't tell you
This is where I'd start documenting. Not every node needs an explanation, but the decisions behind them usually do. These are the things I'd want the next developer to know without having to inspect every connection or run the workflow in debug mode.
1. The trigger
A trigger is more than just the starting point. I'd document what has to be true before the workflow even runs. Which fields are required? What happens if one is missing? Can the same invoice accidentally trigger the workflow twice?
Those assumptions aren't visible on the canvas, but they determine whether the workflow behaves as expected.
2. The branching logic
An If node shows that a decision is being made. It doesn't tell you why that decision exists. I'd document the business rule behind each branch so the next developer understands the reasoning instead of reverse-engineering it from a list of conditions.
3. The failure paths
Every workflow has a happy path. I'd document the unhappy ones too:
- What happens if the approval request times out?
- Does the workflow retry automatically?
- Does the invoice stay pending?
- Is manual intervention required?
- Where should someone begin debugging?
For example, in this workflow a duplicate invoice could quietly slip through if the trigger fires twice before the status updates. That's the kind of edge case you won't spot by looking at the workflow, but it's exactly the kind of thing future maintainers need to know.
Keep the docs where the workflow lives
If I were handing this workflow over to a team, I'd keep the documentation in the same repository as the workflow export. Nothing complicated, just a README.md covering the workflow's purpose, key assumptions, external dependencies, and the failure scenarios someone is most likely to run into.
Documentation gets outdated when it lives somewhere people rarely visit. Keeping it next to the workflow makes it much more likely to be updated alongside the automation itself.
One thing I'll keep doing
Building this workflow reminded me that a successful automation isn't just one that runs reliably. It's one another developer can understand, maintain, and troubleshoot without starting from scratch. I'd want the next developer to understand more than the sequence of nodes. I'd want them to understand the decisions behind them.
I write technical content and documentation for SaaS companies. If you're building something and the docs are the last thing on your list, my portfolio shows how I handle that.
Top comments (0)