As my stories start to grow, I’m finding them harder to follow and maintain. I’m curious how others approach structuring more complex workflows. Are there naming conventions, layout habits, or design patterns that have made a real difference for you? I’d love to build good habits early rather than untangle a mess later.
Great instinct to think about this early! Retrofitting structure into a messy story is significantly harder than building it in from the start. A few things that make a big difference:
Naming conventions. Give every action a clear, descriptive name that tells you what it does at a glance. When you’re looking at a story with 30+ actions, “Get user details from Okta” is much easier to scan than “HTTP Request 4.” This also matters because action names appear in logs and run results, so clear names make troubleshooting faster.
Notes and descriptions. Use story notes to document what the story does, any prerequisites, and anything a future reader (or future you) would need to know. For individual actions, the description field is useful for explaining non-obvious logic.
Layout. Keep your story flowing top to bottom, group related actions visually, and use spacing intentionally. If two branches do different things, separate them so the visual layout reflects the logical structure.
Modularity. When part of a workflow is reusable or getting unwieldy, break it into a separate story and call it using the Send to Story action. This keeps individual stories focused and easier to test.
We cover story design in our Builder: Core learning path in Tines University, and the Story Library is worth browsing just to see how well-structured stories are laid out in practice.