Authoring Stories
The mental model
A story is a narrative walkthrough — a short, readable account of how a specific person accomplishes a goal using the system. It answers: “What does this experience feel like from the user’s perspective?”
Stories are not user stories in the Agile “As a X, I want Y, so that Z” sense — though they may start that way. They are richer: a paragraph or two of narrative that connects a role to one or more features, describing the journey in human terms.
Why stories exist
Features describe capabilities. Flows describe sequences. But neither captures the holistic experience — the motivation, the context, the emotional arc of using the system. Stories fill this gap.
They serve three audiences:
- Designers — understand the user’s mindset and context
- Developers — see the big picture beyond individual features
- Stakeholders — validate that the system serves real needs in plain language
How stories connect the spec
A story explicitly links three concepts:
- role — the actor experiencing the journey (via the
roleattribute) - features — the capabilities being used (via the
featuresattribute) - flows — implicitly referenced by describing the same sequences in narrative form
{% story id="save-bookmark" role="user" features="feature/add-bookmark feature/tag-bookmark" %}The compiler generates cross-reference links from the story to its related features and the role definition.
When to create a story
Create a story when:
- A user journey spans multiple features and you need to communicate how they fit together
- Stakeholders need to validate the experience without reading technical specs
- The interaction has emotional or contextual nuance that flows cannot capture
- You want to test whether your features actually compose into a coherent experience
Do not create a story for every feature. Stories are for multi-step journeys where the connections between features matter as much as the features themselves.
Writing good narrative
Write stories in present tense, third person (or first person from the role’s perspective). Keep the language concrete and specific:
Good: “She pastes the URL into the sidebar. The title auto-fills from the page metadata. She adds two tags from her recent history and confirms.”
Weak: “The user can save bookmarks with tags.”
Include sensory details that reveal design assumptions: where does this happen on screen, what feedback does the system give, how long does it take?
Scope and length
A story should be 3-8 sentences of narrative prose. It is a scenario, not a novel. If your story exceeds a paragraph, consider whether you are actually writing a flow in prose form — if so, extract the flow and keep the story as a high-level summary.
Common mistakes
| Mistake | Why it hurts |
|---|---|
| Too granular | One story per feature creates noise. Stories should span multiple features to show how they compose. |
| Duplicating flow content | If you write step-by-step instructions with branching logic, you are writing a flow. Stories are narrative, not procedural. |
| Missing role attribution | A story without a role attribute has no actor. Every narrative needs a protagonist. |
| Vague narrative | ”The user does things and is happy” communicates nothing. Be specific about actions and outcomes. |
| Feature list masquerading as story | Listing features a user can access is not a narrative walkthrough. Tell the journey, not the inventory. |
| No features referenced | A story that does not declare its features cannot be cross-referenced. The compiler needs these links. |
Evolution
Stories evolve as the product vision clarifies. When features change significantly, review the stories that reference them. When new features are added that affect an existing journey, update the story to incorporate them. Stories may also span milestones — a journey imagined in milestone 1 might only become fully realizable in milestone 3.