How to document your n8n.io Workflow

n8n.io is very intuitive and flexible when building workflows. This flexibility allows for fluid workflow building in a clean interface. I was able to build seamless workflows, but as my workflow was maturing into a usable product, documenting the workflow steps, configurations, and instructions posed a challenge.

There's no best practice in documenting n8n.io, but there are things you can do to maintain the integrity of your documentation.

There's no best practice to document a n8n.io workflow, but through exploring loads of workflows, and my own experience in governance documentation, code review, and formalizing output, here are my tips to ensure that you have good documentation to support your workflow.

Sticky Notes

Sticky notes are flexible and easy to use. It's a feature built in n8n. You can resize them and drag them anywhere on the screen. The best way to use these is when you have short byte-sized notes. If you have a large workflow, or lots of text to write, these can become cumbersome and ineffective.

Node Notes

Every node has a "Notes" field under the "Settings Tab". This is a reliable way to add notes or descriptions. My recommendation is to use this in a way that describes your node, limitations, do's and don'ts, and any instructions that are necessary for the operation of this node. This will come handy later (keep scrolling and you'll find out why).

Workflow Description

Every workflow has a Description field that you can reach when clicking on the ... in the upper right corner. This is helpful but only serves to describe your workflow. Not the best use to get into in-depth documentation of your nodes.

AI Generated Document Generation

Every workflow built in n8n can be downloaded as a JSON file. This structured file carries all attributes of your workflow including your sticky notes, notes, and descriptions.

When I completed my workflow, with all notes and descriptions embedded, I asked Claude to write documentation that describes, the workflow. I was impressed with what it returned.

Reviewing the output, it was thorough, well formatted, and provided the depth I needed for a complete document. Because of the nature of the structured nature of the JSON file and the completeness of my notes, this proved to be very effective.

Automate Your Documentation

To produce consistent results, you can automate your documentation by creating a workflow that utilizes an AI Agent. This workflow would take in the JSON as input, and with an explicit prompt with formatting instructions (e.g. sections required, tables required, format) would produce the content needed. The output would either be inserted into a Google Document, or a PDF, and you can utilize a template if needed. The only caveat is that there are limitations in the format of the output produced. You'll spend some time getting the template setup and will have to test the flow to ensure that it's inserting the text in the right locations and in the right format. I would take this approach if your organization requires consistent documentation in a specific format and requires a large amount of documents to be developed.

In Conclusion

The flexibility and fluidity of building workflows allows for a lot of creativity. You must document your workflow appropriately throughout. By using, sticky notes, notes, description fields, and naming your nodes appropriately, you will maintain the long term integrity of your workflow if you ever need to come back to maintain or edit it. Additionally, if your documentation is complete, AI assisted document generation will be complete and readable without having the AI to make assumptions based on what it's interpreting.