Use the toolbar button highlighted below to show or hide the panel which contains new note stacks. Here you can capture description of new Rules, Scenarios etc. and then drag the notes to the right.

Once the notes have been dragged to the right they become part of the Feature file and are persisted when you press the Save button.

Always show new Story notes
By default new notes stack for User Stories gets hidden once you have dragged over at least one user story note to the right. It can however be made always visible via the editor option menu highlighted below.

This can be useful when you need to split the current user story into further separate stories. You can temporarily capture the newly split story onto another User Story note card in the current Feature before creating a new Jira issue and moving it there under its own Feature panel.

Slide out from the right

The new notes panel can be configured to slide out from the right rather than from the left using the menu option highlighted below

Place the mouse cursor at the bottom of any note so that the note’s drag handle becomes visible. Then click and hold the left mouse button to “grab” the note. Move it with the mouse to the desired location and then release the mouse button to drop the note.

The locations where a particular note can be dropped is colour highlighted when the note is dragged over it. The note will be auto aligned after dropping so you don’t need to be precise with positioning. Where exactly each type of note can be dropped is explained in the following sections.

Dropping User Story Notes

User Story notes are top level elements and can be dropped onto an empty space or next to other User Story notes dropped earlier.

More than one User Story note

At times you might discover another User Story not previously known as part of your team’s Example Mapping discussions. When this happens it is useful to be able to capture it quickly under the same feature so that it doesn’t get lost and then later after the meeting move it out into its own Jira issue and Feature panel.

Dropping Rule Notes

Rule notes can be dropped onto a User Story note that doesn’t yet have any Rule notes

Or next to other Rule notes dropped earlier

Or onto a User Story note that is currently folded (see Fold Note Groups)

Dropping Scenario Notes

Scenario notes can be dropped onto a Rule note that doesn’t yet have any Scenario notes

Or next to other Scenario notes dropped earlier

Or onto a Rule note that is currently folded

Story scenarios
Cucumber syntax supports having Scenarios without a preceding Rule, so you can also drop a Scenario note directly onto a Story note

See below for difference between a Scenario that belongs to a User Story vs a Scenario that belongs to a Rule

Dropping Question Notes

Semantically questions can belong to User Stories, Rules or Scenarios, so you can drop them accordingly

You can also drop a Question note onto Story, Rule or Scenario note that is currently folded

Dropping Step Notes

Unhide Step notes

Step notes are hidden by default, but they can be made visible by unchecking the editor menu option shown below

Step notes can be dropped onto folded Scenario notes or next to other Scenario steps or question notes like shown below

Steps & questions mixed

Step and question notes that belong to a Scenario can be arranged in any order like shown in example below

Notes can optionally be configured to show the leading keywords that are there when viewing the corresponding lines for the note in the Gherkin Text Editor mode. These leading keywords cannot be deleted when editing the note’s text.

User Story Note Keywords

Use the preferences menu option highlighted below to show / hide the 'Feature' keyword.

The common user story keywords 'As a’, ‘I want to’ and ‘So that’ get added automatically to new User Story notes but can be changed or deleted if required.

Rule Note Keyword

Use the preferences menu option highlighted below to show / hide the 'Rule' keyword.

Scenario Note Keyword

Use the preferences menu option highlighted below to show / hide the Scenario Note keyword.

Change Scenario keyword

Gherkin syntax supports one of: Scenario, Example, Scenario Outline and Scenario Template as leading keywords for a scenario. You can quickly change between these on a Scenario Note by hovering the mouse over the keyword and then clicking the left mouse button while holding the 'Alt' key. Then pick a different keyword from the drop down menu as shown below.

Question Note Keywords

Use the preferences menu option highlighted below to show / hide the 'Q' keyword.

The ‘A:' keyword used as a prefix before the answer to the note’s question is automatically added to the Question Note when ‘show keyword’ option is turned on, but can be deleted or added as required.

Note that if there is some text entered after the ‘A:' keyword the question is considered answered, see more information related to this in Capturing Questions & Answers.

Step Note Keywords

Use the preferences menu option highlighted below to show / hide the Step Note keyword.

Change Step keyword

Gherkin syntax supports one of: Given, When, Then, And or But as leading keywords for a step. You can quickly change between these on a Scenario Note by hovering the mouse over the keyword and then clicking the left mouse button while holding the 'Alt' key. Then pick a different keyword from the drop down menu as shown below.

Note that if a Step Note has keyword ‘And' or ‘But’ and it is moved to be the first step of a Scenario then the keyword will change to one of ‘Given’, ‘When’ or ‘Then’ since ‘And’ and 'But’ cannot be the first Step keywords of a Scenario.

Semantically related notes are grouped together for selection, copying and drag & drop operations. Ensuring that the preferences menu option highlighted below is checked will show a border around note groups.

User Story Group

Click on the drag handle of a Story Note to see an outline border around all Scenario, Rule and Question notes that semantically belong to the selected User Story

Rule Group

Click on the drag handle of a Rule Note to see an outline border around all Scenario and Question notes that semantically belong to the selected Rule

Scenario Group

Click on the drag handle of a Scenario Note to see an outline border around all Step and Question notes that semantically belong to the selected Scenario

It is often easier to navigate the feature and to perform drag & drop operations by first folding note groups. This is particularly useful in Features with many notes.

To fold a note group, simply select it and press either “Alt+Enter“ keyboard shortcut or hold the “Alt“ key while clicking the note’s drag handle with the left mouse button.

The folded summary is shown to the right of the folded note. It provides a quick visual indication of how many notes have been folded. Hovering over it with the mouse will show a tooltip with the number of individual notes or note groups that have been folded. Clicking on the folded summary will unfold the note group.

Fold User Stories

Folding User Story note group is useful when you want to quickly capture a newly discovered User Story under the same Feature during team discussions.

Fold Rules

Folding Rule note groups can be useful whenever you just want to quickly review the acceptance criteria for a User Story (note that Rules in a Cucumber Feature file essentially are the acceptance criteria), without going into the details of the examples.

Fold all rules
Click on the toolbar button highlighted below while holding the ‘Alt’ key in order to fold all of the Rules in one operation

Click on the chevron double-down button next to it while holding the ‘Alt’ key to unfold all of the Rules

Fold Scenarios

Folding Scenario note groups can be useful when you don’t want to see the details of each of the examples especially when you are working also with the Step notes, as is the case with Feature Mapping.

Fold all scenarios
Click on the toolbar button highlighted below in order to fold all of the Scenarios in one operation

Click on the chevron double-down button next to it to unfold all of the Scenarios

Fold on Page Load

You can configure the Feature panel to have User Story, Rule or Scenario note groups folded every time the issue page loads. This can be useful if you wish to be presented with less information initially and then click to unfold only when you want to see the details.

This can be configured via the preferences menu option highlighted below.

* Note that the “Feature” fold option shown in the screenshot above corresponds to folding the User Story note groups - since the user story text is placed at the Feature cucumber keyword when viewed as a plain text file.

Folding is Linked to Gherkin Text Editor Mode

Folding can be done either via Example Mapping mode or via the Gherkin Text Editor mode. The folded ranges are “linked“ between the two modes - meaning that if you fold a section of lines in Gherkin Text Editor then the corresponding note groups in Example Mapping will get folded also. This can be better seen when viewing the two modes in a side-by-side view, like shown below.

Selected Scenario Note Group above corresponds to line number 9 in the Gherkin Text Editor panel on the right which has been folded.

Feature Mapping is another technique used to facilitate collaborative requirements discovery sessions. It differs from Example Mapping in that it incorporates the use of one additional card category to capture the Steps of an example/scenario, and it uses horizontal alignment (from left to right) for Rule and Scenario elements.

To switch to Feature Mapping view at any time click on the preferences menu option highlighted below.

To make the outcome type steps (i.e. those with the Then keyword) stand out more you can assign a different colour to these notes using the preferences menu option highlighted below.

Unhide Steps
Step Notes are hidden by default. To make them visible uncheck the preferences menu option highlighted below.

The customizations explained in the following sections apply on per user basis, that is if you change any of the preferences mentioned it will apply to you only and others will see the Feature according to their preferences.

Size & Shape of Notes

Each of the note types can be configured to be of size: Small, Medium or Large and shape: Square or Rectangle.

Additionally Story and Step Notes can be of Extra Large size.

Start with large and transition to small

When you first capture a User Story it might not be very obvious what are the rules and/or examples that will go into respective notes under this user story. So you might want to capture all the information that you know at the time about the user story in a free form text on an Extra Large User Story Note without worrying what is a Rule or what is a Scenario exactly etc.

Then later when you have more information and are discussing the User Story during your team’s Example Mapping sessions, you can structure the information more into Rules, Scenarios, Questions etc. and make the User Story Note itself smaller.

Note Colours

You can change the preferred colour used for different note types, see example below showing where this can done for a Story Note. The colour shades available for each note type are close to the colours originally suggested by the authors of the Example Mapping and Feature Mapping techniques.

Note Border Outline

You can optionally show/hide a border around individual Notes or Note Groups using the preferences menu options highlighted below.

You can also change border colour.

Note Spacing

Use the preferences menu option highlighted below to change the note spacing.

Wide

Normal

Compact

Tight

Drag Handle

Use the preferences menu option highlighted below to configure options for note drag handle.

Top placement

Bar shape

Diamond shape

None

The note remains draggable by the bottom portion even though there is no drag handle symbol

Different colour and glow effect

Line Numbers

Use the preferences menu option highlighted below to show line numbers in each of the note’s gutter

The line numbers correspond to where the note’s content is located in the overall Feature file. This can be better seen when viewing the two modes side-by-side.

Linked Selection & Scrolling

When the preferences menu option highlighted below is selected and the editor is shown in a side-by-side view then whenever you select a note in the left pane the editor on the right will automatically scroll to and highlight the lines where the note’s content is located. Automatic selection and scrolling works in the other direction also.

This can be useful when you want to find where exactly is a particular note’s content located in what could be a longer Feature file.