User Story Card Clarified
Avoid storing user stories in digital forms, such as JIRA. Use physical index cards instead.
This article is one of the “IT Terminology Clarified” series.
Not long ago, I heard a junior team member asked: “What is a story card?”. A programmer answered: “A requirement in JIRA”. Then he showed the JIRA board like below:
Here I have to say that the common view the programmer held about User Story Card is not correct.
Table of Contents
· History of User Story Card
· My understandings of User Story Card
∘ User
∘ Story
∘ Card
· Summary
· My User Story Card looks like thisHistory 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 is “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’ 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
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 probably 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 be complete, precise, or in great detail initially. 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-n-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
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. If these automated tests are well maintained, the business logic will be captured there. This is BDD (Behaviour Driven Development).
Card
Write user stories on index cards, not in a digital management system such as JIRA.
If a user story (written by a business analyst) is turned redundant or to be included in another one, you just tear it off. If one user story seems too abstract, break it into multiple user stories, i.e., tear it off and write it down in several new index cards. You don’t need to log on to JIRA to delete it or drag it to the ‘backlog’. By doing that, some might probably worry about velocity…, etc.
There are other subtle benefits of physical cards. Once a team member finished the task (coding or testing), he stood up and put the card in the next column. This gives him the satisfaction of being ‘Done’ (with a touching sense). By the way, regular stand-ups are good for programmers, as an Apple Watch would tell you.
Q & A
Handwriting in physical story cards is hard to read!
Yes, your observation is correct. Unfortunately, most people's handwriting nowadays is quite bad (thanks to the use of computers). The agile board in JIRA does look a lot neater. However, this simple reason is NOT good enough to use JIRA.
In fact, this can be solved easily. I once created a free software StoryWise (now deprecated) which had a feature: printing user story onto an index card. It is not hard to do.
Summary
The purpose of a User Story Card is to foster communication among the software team members, not aiming for detail to perfection. This is in line with the Agile Manifesto.
Instead of wasting a lot of time on the meaningless process, we shall focus on delivering the features to make them available for the customer to try promptly, ideally in hours instead of days or weeks. This is the winning formula.
Expecting 100% perfectly detailed user stories in JIRA and asking developers to code and testers to test rigorously sounds like WaterFall to me.
In reality,
customers may not know exactly what they want
business analysts may misunderstand the customers’ requirements
business analysts may not write down the customers’ requirements clearly
developers and testers may understand the text in JIRA wrongly
After all, the application under development could change constantly and rapidly. With that in mind, the whole JIRA game sounds silly, doesn’t it?
“only dead fish go with the flow” — proverb
Some may say: “yes, that’s the true nature of software development. Does it mean that it is pointless to capture the criteria for the requirement?”
No. Business analysts and customers need to come out with acceptance criteria, but they do not always need to write them down in a text document. Convey the information to SETs (Software Engineer in Test) who can translate the acceptance criteria into one or more automated E2E test scripts. In this way, you will have live specifications if you maintain the tests well (you should if you use CI/CD or CT/DevOps).
My User Story Card looks like this
I still use the format that I learned from the agile coach in 2005. The three colour boxes work as below.
After BA understood the requirement, he/she coloured the red box.
After the developer implemented the feature (code and automated E2E tests), he/she coloured the blue box.
After the on-site customer/manual tester/BA/Manager verified the feature (in the system), he/she coloured the green box.
We encourage conversation among the team members who are working on this user story. The physical card (being carried with them) provides the scope and context for the discussions.
After the green box is filled, the life of this user story ends. It would be put on the storyboard (physical). After the sprint/iteration, ‘green’ story cards will be torn off. No one cares about completed user stories anymore, as they are captured in automated E2E tests.
Some might ask: “What would happen if there is another update to a completed user story?”. Write a new story card for it. Done is Done.
It is important that all automated E2E tests will run in a CT server multiple times a day. Without solid test automation and a Continuous Testing process, real Agile is simply impossible.
Further reading: