Cover image from Story Templates

Story Templates

April 26, 2019

I have been looking after some JIRA boards recently. Our team has developed some templates for outlining the requirements. We use the following ticket types:

  • Epic
  • Story
  • Improvement
  • Bug

Epic and Story

{color:red}This is a work in progress{color}

h3. As a ...

\*Pre Conditions\*
\*

\*Acceptance Criteria\*
\*

\*Acceptance Test Scenarios\*
{noformat}
  Scenario:
    Given
    When
    Then
{noformat}

\*Notes\*
\*

This is a template for defining the requirements for a user feature.

Lets break it down

In Progress

{color:red}This is a work in progress{color}

Pretty straightforward. I won’t address it again, simply makes explicit to others that this story is still being worked on and shouldn’t be assumed to be final.

User Story

h3. As a ...

Probably the most important element of the story. Firstly we have to decide on what the role for the story is; “As a logged out user”, “As an API consumer”, “As a developer”. The role has a large part to play in what is taking place that is part of the requirement.

Next is the action element. What is it that the user denoted in the role is looking to do? For example; “… would like to log in”, “… would like to query films by name”, “… would like to have a method to access data”.

Lastly, the reason for the story. Definition of the purpose of the user denoted in the role performing the action denoted can be very illuminating. Many refinement sessions I have taken part in have pivoted direction drastically as a result of this. For example; “As a logged in user I would like to log in so that I can perform logged in actions”.

Pre Conditions and Acceptance Criteria

*Pre Conditions*
  *

*Acceptance Criteria*
  *

Pre Conditions is a list of things which are required for the story to be valid. Examples might be; user needs to be logged in, there needs to be valid items in the shopping cart. Any third party dependencies could be listed here as well.

Acceptance Criteria should be a definitive list of what conditions need to be satisfied in order for this story to meet the definition of done. Time should be taken on this step. I like to think that if something is missed from this section it is not appropriate to tell an engineer their solution is missing something. If developers are to trust the story format the Acceptance Criteria section should be something that they trust during development to consult to see what is needed to call the ticket finished.

Acceptance Test Scenarios

*Acceptance Test Scenarios*

{noformat}
  Scenario:
    Given
    When
    Then
{noformat}

Probably the first non-standard section. We began adding this section recently. The purpose is to keep everything together. The format is Gherkin syntax. I have some more information about this format here. This is done even if Cucumber is not being used for the actual Acceptance Tests. It is used purely as a format for defining a multi-step test. Here we can explore happy path and negative scenarios. These sometimes feed back into Acceptance Criteria that were missed.

The key advantage of this section is that it forces engineers to mentally delve deeper into the story and its practical impacts. It does this in a manner which is English like and expressive. This increases the shared understanding in the team and can reduce misunderstandings. The effect that two engineers come out of the same conversation with diametrically opposed view of what was agreed is more difficult because it is written down.

Notes

*Notes*
  *

This is what it seems like. Any notes to the team, stakeholders, posterity, or yourself should be added here. I won’t address this again.

Improvement

h3. Reason

[Insert reason for improvement]

h3. Implementation

[What needs to be done for improvement]

h3. Verification

[How do we now the improvement is successful]

Simpler ticket type which is designed for non-user facing changes which are purely technical in nature. We introduced this when it became obvious it wasn’t feasible to have a full refinement session for technical tasks where the user value isn’t as obvious.

Split into three sections we outline:

  • Reason - Why are we performing this task
  • Implementation - What needs to actually be done
  • Verification - How do we know it is completed

It really is the stripped down version of the Story format. It is just enough to give context and document implementation for engineers.

Bug

h2. Steps to Reproduce
  *

h4. Expected Result

h4. Actual Result

This template is designed to encourage the composer of the ticket to specify how the person who is picking up the ticket can replicate or view the issue.

Additionally, a Bug is generally understood to mean that an application is performing an operation in a manner that does not comply with its original design. The “Actual Result” heading prompts the ticket author to answer the question; “What is it you expected to happen”. This can often be identifying what are in fact feature requests and change requests in bug tickets.

Tags
Agile