Pixtex
GuidesOpen the editor →
Agencies

How to document an n8n workflow for a client

By Muhammad Muneeb · · 7 min read

A client cannot read workflow JSON and should not be sent a screenshot of your n8n tab. The handover that works is three artefacts: one overview image of the whole flow, one close-up image per branch that matters, and a short written description of each trigger and its failure path. Render all of them from the workflow itself so the pack can be regenerated in a minute when the build changes.

What the client is actually asking for

“Send me the documentation” almost never means “send me the JSON”. It means one of three things, and they want different artefacts:

  • “Show me what I paid for.” One picture of the whole flow, clean enough to put in a slide deck.
  • “Explain what happens when X.” One picture per branch, with the relevant path highlighted and everything else faded back.
  • “What do we do when it breaks?” Written: the trigger, the failure mode, who gets alerted, and how to re-run it.

None of those is served by a JSON file, and only the first is served badly by a screenshot.

A handover pack you can rebuild in a minute

  1. 01
    The overview image

    Whole workflow, auto-layout on if the client's canvas was arranged by whoever dragged last, node detail on standard, title overlay on. This is the picture that goes on page one and into the proposal. Export at 3× or 4× so it survives being dropped into a deck and blown up.

  2. 02
    One image per branch that matters

    For each meaningful path — the happy path, the retry, the refund, the escalation — render the sameworkflow with that path's connections highlighted and the rest dimmed. Same layout every time, so the client is looking at one map with different routes traced on it rather than five unrelated pictures.

    Label the connections while you are there. only if paid, after 3 retries, weekdays only — the labels carry the business rules that the node names do not.

  3. 03
    Sticky notes for the why

    n8n sticky notes come through into the render, and you can edit them in the Pixtex editor without touching the client's live workflow. That makes them the right place for the sentence that explains a decision — “we poll instead of using a webhook because their firewall blocks inbound” — which is exactly the knowledge that evaporates when the person who built it moves on.

  4. 04
    The PDF

    Export the overview as PDF for the signed-off deliverable, and keep the PNGs for the pages and slides. See exporting to PDF and SVG for what each format does and does not preserve.

Make it regenerable, not a one-off

The reason handover documents rot is that rebuilding them is manual. Take the manual part out: connect the client's n8n instance and re-pull the workflow, or host the overview diagram at a permanent URL and re-render it in place so the copy in their Notion updates itself. That is the README guide, and it applies to a client wiki just as well.

Three things to leave out

  1. Credentials. Not in the doc, not in a screenshot of the credential panel, not in the JSON attachment. A password manager share, or nothing.
  2. Pinned execution data. Workflows that were tested against real records carry those records in pinData. That is customer data sitting inside an export — what is actually in a workflow export covers how to check.
  3. Your internal node names. HTTP Request3 tells the client nothing. Rename before you render; the render reads the names off the workflow.
If you do this for more than one client, keep one style — same background, same icon pack, same frame — and set it from the API rather than by eye. The options in the editor and the options in POST /v1/render are the same names with the same values, so a house style becomes a JSON snippet you reuse. The API reference lists all of them.

Questions

What should an n8n handover document contain?

An overview diagram of the whole workflow, a close-up image of each branch that has business logic in it, a plain-language description of every trigger and what it costs to run, and the error path — what happens when a step fails and who finds out. Credentials belong in a password manager, never in the document.

How do I show one branch of a workflow without cropping the picture?

Highlight the connections on that path and dim the rest. The reader keeps the context of the whole workflow and still sees exactly which route you are describing — a crop throws that context away.

Can I hand over a PDF of an n8n workflow?

Yes. Export the rendered canvas as PDF — one page, sized to the workflow. The page embeds the rendered image, so the text is not selectable, which is usually what you want in a signed-off deliverable.

Try it on your own workflow

Drop a workflow JSON file on the editor and export a PNG, SVG or PDF. Free, no account, nothing to install.

Open the editor →Render it from code
read next
How to export an n8n workflow as an image
n8n exports workflows as JSON, not pictures. Here is how to turn that JSON into a clean PNG, SVG or PDF of the canvas — by hand, from the CLI, or automatically in CI.
How to share an n8n workflow safely
Exported n8n workflow JSON can carry pinned customer data and inline API keys. Here is what is in the file, how to check it, and when to send a picture instead.
Export an n8n workflow to PDF or SVG
Print-ready and scalable exports of an n8n workflow — what PDF and SVG actually preserve, and which one to pick for a deliverable, a docs site or a poster.