# User Stories in Flowriter

A User Story in Agile documentation describes a small, specific piece of functionality from the user's perspective. 

While an Epic is like a big project goal (e.g., "Build a shopping cart"), the User Stories inside it are the smaller, specific tasks needed to achieve it (e.g., "Add items to cart," "Remove items from cart," "Calculate total").

In Flowriter, User Stories ("Stories", or "Story") are contained in Epics. A Story in Flowriter has the following features.

## Name

This can be anything you like. User Stories are often named using **Role, Goal, and Benefit** statements e.g. `"As a user...I want ... so that..."` . 

You can (but don't need to) use that format for the Story name in Flowriter. A Role, Goal, and Benefit statement will be automatically generated by Flowriter as part of the Acceptance Criteria later.

{% hint style="info" %}
If you plan to use Flowriter's automatic flowchart generation, the Story name should be descriptive. The AI will refer to this when composing the flowchart.
{% endhint %}

##

## Language

Automatically generated Story content such as flowcharts, Acceptance Criteria, and Test Script comments are generated in the default content generation language. This is first set when you created your account, and can be changed at any time in the [Story Settings](https://candesce.gitbook.io/flowriter/user-stories/change-a-storys-language).

{% hint style="info" %}
If you manually create a Story flowchart in one language, you can generate the User Story content such as Acceptance Criteria and Test Script comments in a different language. 

Flowriter will handle the translation for you.

For example, if you create a flowchart with `English` text and set that Story's language to `norsk (Norwegian)` Flowriter will retain the flowchart (and User Journeys) in `English` and generate Acceptance Criteria and Test Script comments in `norsk (Norwegian)`.

This might be useful if you need to generate documentation that targets different audiences.
{% endhint %}

See: [Supported languages](https://candesce.gitbook.io/flowriter/getting-started/supported-languages)

##

## Flowchart

A Story's flowchart is where you visually define the actions, decisions, and notes about how a user or system might navigate a feature or service. 

<figure><img src="https://619360366-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvFE09GWUQiR5kjeutlr2%2Fuploads%2FC1oqwQfYWTCrkYOzytac%2FScreenshot%202025-01-12%20at%2011.42.08.png?alt=media&#x26;token=fe07ed55-a465-4f19-9382-f1ad5b8a6b9b" alt="" width="563"><figcaption></figcaption></figure>

Flowriter will analyze your flowchart to automatically extract User Journeys, write Acceptance Criteria, and prepare Test Scripts to implement and test all the potential actions and outcomes of the feature.

See: [Flowcharts](https://candesce.gitbook.io/flowriter/working-with-flowcharts/flowcharts-in-flowriter)

##

## User Journeys

User Journeys outline the steps and decisions users make to achieve their goals, and inform the Acceptance Criteria:

<figure><img src="https://619360366-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvFE09GWUQiR5kjeutlr2%2Fuploads%2FOYeYsUhGxBxVwQ82S3gl%2FScreenshot%202025-01-12%20at%2011.42.17.png?alt=media&#x26;token=463d49ff-e401-40e4-b2e0-b92adbc87f33" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
User Journeys are useful for preparing Test Plans, and can be exported as CSV files for import into tools like JIRA.&#x20;

They ensure that all possible steps and decisions a user could take when using the feature are accounted for in testing the implemented feature.&#x20;
{% endhint %}

During the generation of the Acceptance Criteria, Flowriter analyzes your flowchart and identifies all possible "paths" that a user (or system) could take when using the feature.&#x20;

These are summarised into separate Goals, each consisting of a series of steps and decisions.

##

## Acceptance Criteria

A Story's Acceptance Criteria is automatically generated, and consists of two (2) parts:

<figure><img src="https://619360366-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvFE09GWUQiR5kjeutlr2%2Fuploads%2F5MBorbx3dZU6AfZNEh5z%2FScreenshot%202025-01-12%20at%2011.44.52.png?alt=media&#x26;token=1cbad627-c49f-4bbc-b3aa-e231d6e1a10a" alt="" width="563"><figcaption></figcaption></figure>

#### Role, Goal, and Benefit statement

This summarizes the overall feature described in the flowchart and identified User Journeys, and is presented in this format:&#x20;

`As a [user/system/...] ... I want to ... So that ...`&#x20;

#### Gherkin -style Feature/Scenario statements

These defines how the feature should behave based on User Journeys. These criteria are generated in [Gherkin](https://cucumber.io/docs/terms/user-story/), a structured format that can be read by both humans and scripts.&#x20;

{% hint style="info" %}
You can export Acceptance Criteria as **.feature** files for use with test automation tools
{% endhint %}

##

## Test Scripts

Flowriter can analyze a Story's Acceptance Criteria and generate **Step Definition** test scripts in Javascript:

<figure><img src="https://619360366-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvFE09GWUQiR5kjeutlr2%2Fuploads%2FzVWBBWkkeNjG99RtuBoS%2FScreenshot%202025-01-12%20at%2011.45.40.png?alt=media&#x26;token=61539e79-530f-4b5b-ba5b-4fc9feab2d0f" alt="" width="563"><figcaption></figcaption></figure>

Step Definitions connect steps in Gherkin -style Acceptance Criteria to programming code. In most cases, a Test Script is generated per Scenario in the feature. They can be used to kick start automated testing of the feature described in the Story, using tools like [Cucumber](https://cucumber.io/docs/).

{% hint style="info" %}
You can export Test Scripts as **.js** files for use with test automation tools
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://candesce.gitbook.io/flowriter/user-stories/user-stories-in-flowriter.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.