An Open Letter to the n8n Team:
Better Documentation Is Now a Platform Requirement
n8n has become one of the most powerful automation platforms available today. Its flexibility, strong node ecosystem, and growing cloud and self-hosted offerings make it a critical tool for builders across many industries.
But as adoption accelerates, one issue is becoming impossible to ignore:
n8n’s documentation — especially around node JSON structure and execution rules — has not kept pace with how the platform is actually used.
This isn’t a niche concern anymore. It affects everyone.
How n8n Is Really Being Built Today
Today, many users:
-
Generate workflows with AI tools like ChatGPT
-
Paste node JSON directly into the canvas
-
Treat workflows as code, not just diagrams
-
Build automations that power real, revenue-critical systems
This applies equally to cloud and self-hosted users. The deployment model doesn’t change the core reality: workflows are JSON, and correctness matters.
AI-assisted workflow creation is no longer experimental — it’s normal.
The Problem: Implicit Rules
At the heart of every n8n workflow is a JSON graph:
-
Nodes
-
Parameters
-
Execution modes
-
Connections
-
Metadata
Yet today:
-
There is no formal, versioned node JSON specification
-
Execution modes are under-documented
-
Data shape guarantees between nodes are unclear
-
Many “rules” live in examples, forum posts, or source code
The result is predictable:
-
Workflows that look valid but fail at runtime
-
AI-generated flows that are almost correct
-
Subtle bugs caused by incorrect assumptions
-
Fragile automations that break during upgrades
This isn’t an AI problem.
It’s a documentation gap.
Why This Matters Now
n8n is no longer just a visual automation tool. It’s an automation runtime used by:
-
Individual creators
-
Teams
-
Agencies
-
Startups
-
Enterprises
At the same time, AI is becoming a first-class co-builder. Platforms that clearly define their contracts will thrive. Platforms that rely on tribal knowledge will accumulate invisible technical debt.
What Would Help Most
A few focused improvements would have outsized impact:
1. A formal, versioned node JSON schema
Clear definitions of required fields, valid parameters, and execution metadata.
2. Explicit execution contracts
When to use each execution mode, what data shapes are guaranteed, and what patterns are unsafe.
3. Clear data shape guarantees between nodes
Most workflow bugs aren’t logic bugs — they’re shape mismatches.
4. Upgrade-safe guidance
Documented anti-patterns, deprecations, and forward-compatible design rules.
These improvements benefit everyone:
-
Cloud users
-
Self-hosted users
-
Beginners
-
Advanced builders
-
Humans and AI alike
A Real Opportunity for n8n
With clearer, more formal documentation, n8n could:
-
Become the most AI-friendly automation platform available
-
Reduce support and forum noise
-
Improve workflow reliability across versions
-
Make advanced usage safer without making the product harder
This isn’t about criticism. It’s about alignment with how people actually build systems today.
Final Thought
n8n’s flexibility is its superpower.
But flexibility without clearly documented contracts eventually becomes fragility.
Better documentation — especially around node JSON and execution rules — wouldn’t just help AI write better workflows.
It would strengthen the entire n8n ecosystem.