Narration style guide
Good notes turn a workflow from a wall of steps into something anyone can read. This is the house voice — the style our own flows use, the one the AI drafts imitate, and the one published flows are encouraged to match.
The voice, in one line
Section titled “The voice, in one line”Write what the step does for the person — the outcome, not the mechanics.
- Lead with the result. What does this step accomplish?
- One or two short sentences. A note is a caption, not a manual.
- Present tense, second person. “Emails you…”, not “Will send an email”.
- Plain language. No jargon, no node names, no configuration detail.
- Say why it matters when it helps (“…so nothing slips”).
Do / don’t
Section titled “Do / don’t”| Instead of… | Write… |
|---|---|
| ”HTTP GET request to /orders endpoint" | "Grabs your latest orders so the flow can work with them." |
| "Discord webhook POST" | "Posts your message to the right channel so the team sees it." |
| "Cron trigger 0 8 * * *" | "Runs every morning at 8am." |
| "Append row to Sheet1" | "Adds each new entry to your sheet so nothing is lost." |
| "Create Linear issue via API" | "Files a new issue in Linear so the request doesn’t slip.” |
Where notes appear
Section titled “Where notes appear”A note you write shows up as a sticky-note callout on its step, and the How this flow works panel reads all of them in order as a plain-language story — so a flow you share teaches on open.
Let the AI draft, then edit
Section titled “Let the AI draft, then edit”You don’t have to start from scratch: ✨ Draft with AI writes a note in this voice for a step (or for every un-noted step at once), and you edit and approve it. See Notes & story.
Why it matters for publishing
Section titled “Why it matters for publishing”A flow where every step is narrated earns a ✨ Narrated badge on the Marketplace and reads like a walkthrough for whoever installs it — the whole point of sharing a flow is that the next person can learn it, not just run it.