User Story Card Clarified, Part 1

This article is one of the “IT Terminology Clarified” series.

Not long ago, I heard a junior team member ask: “What is a story card?”. A programmer answered: “A requirement in JIRA”. Then he showed the JIRA board like below:

Here, the common view this programmer held about User Story Card is incorrect.

History of User Story Card

I will first explain the history of the User Story Card.

Fact: The success of Agile is before JIRA

Prior to Agile, the common term for the software requirement was “Use Case” (it was quite a big thing, here is a link to Use Case books on Amazon). A Use Case is often tied with Rational processes such as Use Case Modelling, which was later proved heavyweight. Due to many problems with the actual use of Use Case in practice: too formal (such as the modelling process) and encouragement for traceability (which is time-consuming, often wrong and has no practical benefits), the term ‘Use Case’ has been gradually deprecated since 2006.

User Story is the term introduced in Agile. In 2004, the book “User Stories Applied: For Agile Software Development”, written by Mike Cohn, was published. Since then, with more software projects adopting Agile, software requirements have been known as User Stories. But where does the word ‘Card’ come from? A user story was written on a physical index card (see the picture below). I will explain more about this later.

After knowing the failed ‘Use Case’, it is easier to see why the commonly-seen JIRA User stories are often wrong. I would recommend reading the classic “User Stories Applied” book, but I know many people won’t. Therefore, I will quickly share my understanding.

My understanding of User Story Card

Every word in “User Story Card” has its own meaning; the purpose is to address the shortcomings of failed Use Case paradigm.

User

A User Story shall be written from a user’s perspective. However, if you have a look at the user stories in your project, I bet that quite a number of them are not from the user’s perspective. For examples:

• Set up Git repository on BitBucket
• Set up ElasticSearch server for full-text search
• Configure a Docker container to use for authentication service
• Create a Git branch ‘xxx’ for ….
• …

The users do not care about the above.

Another important attribute of ‘User’, in this context, is testability which mostly means functional testing. For the content of the user story card, a user shall be able to verify it (in other words, testing). Functional testing (against a user story card) in a real agile team is largely done via automation. What I mean is to run all automated end-2-end UI tests (in a web browser for web apps) in a Continuous Testing server multiple times a day.

Q & A

1. Where are the acceptance criteria for testing a physical story card?

A: The acceptance criteria can be written on the back of the card. If there is not enough room, you should break this into two or more story cards.

Story

To be informal. Imagine telling stories to a child. The words/sentences may change every time, but the purpose is to get the main idea across.

A user story does not need to initially be complete, precise, or in great detail. Realistically, a customer won’t foresee every detail of a requirement, let alone the interpreted version (from the customer’s knowledge) by a business analyst. Acknowledging this simple fact will make everyone’s life easier.

In my opinion, the common issues with user stories in JIRA are:

• Too much detail

This means more mistakes or being out of date quickly. For the two recent client projects, I found that over 90% of JIRA user stories contained errors from the functional tester’s perspective. This became more obvious when real test automation (regression testing daily) was in place.

• Look similar

Copy-and-paste is easy to do with JIRA, which can generate a large (often wrong) document. Another side-effect is that many user stories look similar (contradicting the meaning of the story), resulting in other team members not reading the content thoroughly. (Try telling your child 10 stories starting ‘Once upon a time’, then follow 5 similar sentences, …).

• Assignment

I don’t like to be interrupted by JIRA notifications (such as assignments or updates). By using physical cards, assignments will be easy. Whoever carries or has the card is the assignee.

• Encourage blaming

I often heard arguments between BA, developers and testers on a specific detail, such as “I did exactly what you wrote on JIRA” and “Yes, but you did not follow updates, ….”

Q & A

1. If a user story is as informal as you suggest, how can we get the source of truth later?

A: The source of truth lies within the software and its users, not some page in JIRA. As I have said before, it is common that a large percentage of JIRA user stories contain errors anyway. We shall all know that anything written down for an ever-changing system will be out of date soon.

The solution to your concern is automated E2E test scripts. The business logic will be captured there if these automated tests are well maintained. This is BDD (Behaviour Driven Development).

--

In Part 2, I will cover the last attribute "Card" and a wrap up.