Liferay.Design / Handbook
Part of Liferay, IncCode/Content LicensesPowered by Gatsby and Netlify


Sign In

What is a Story?

Atlassian defines a story as:

an informal, general explanation of a software feature written from the perspective of the end-user. Its purpose is to articulate how a software feature will provide value to the customer.

User stories could be simply software system requirements. But they're not.

A key component of agile software development is putting people first, and a user story puts end-users at the center of the conversation. These stories use non-technical language to provide context for the development team and their efforts. After reading a user story, the team knows why they are building, what they're building, and what value it creates.

User stories are one of the core components of an agile program. They help provide a user-focused framework for daily work — which drives collaboration, creativity, and a better product overall.

Understanding Stories

Again, a story is the smallest unit of work in an agile framework - as defined by Atlassian documentation. It’s an end goal, not a feature, expressed from the software user’s perspective.

A story is an informal, general explanation of a software feature written from the perspective of the end-user or customer.

The purpose of a (user) story is to articulate how a piece of work will deliver a particular value back to the customer. Note that "customers" don't have to be external end-users in the traditional sense, they can also be internal customers or colleagues within your organization who depend on your team.

Stories are a few sentences in simple language that outline the desired outcome. They don't go into detail. Requirements are added later, once agreed upon by the team.

What else?

Stories fit neatly into agile frameworks like scrum and kanban. In scrum, user stories are added to sprints and “burned down” over the duration of the sprint. Kanban teams pull user stories into their backlog and run them through their workflow. It’s this work on user stories that help scrum teams get better at estimation and sprint planning, leading to more accurate forecasting and greater agility. Thanks to stories, kanban teams learn how to manage work-in-progress (WIP) and can further refine their workflows.

They are also the building blocks of larger agile frameworks like epics and initiatives. Epics are large work items broken down into a set of stories, and multiple epics comprise an initiative. These larger structures ensure that the day-to-day work of the development team (on stores) contributes to the organizational goals built into epics and initiatives.

Creating a Story

Stories sometimes seem like an added step. Why not just break the big project (the epic) into a series of steps and get on with it? But stories give the team important context and associate tasks with the value those tasks bring.

User stories serve a number of key benefits:

A good reference about story benefits:

  • Stories keep the focus on the user. A to-do list keeps the team focused on tasks that need to be checked off, but a collection of stories keeps the team focused on solving problems for real users.
  • Stories enable collaboration. With the end goal defined, the team can work together to decide how best to serve the user and meet that goal.
  • Stories drive creative solutions. Stories encourage the team to think critically and creatively about how to best solve for an end goal.
  • Stories create momentum. With each passing story, the development team enjoys a small challenge and a small win, driving momentum.


Story workflow
Story workflow

Example of a Story:

There are different situations where a Story can be created. The most common in tech is related to "User stories” which are the basic requirements written from the end-user perspective and are considered to be smaller pieces of work within an Epic. So a Story can be understood as a user need related to a product or service.

A typical Story needs to explain how a piece of work can deliver value to the user, client, or stakeholder (who is requesting it). Also, stories help create a context for the design team who will be responsible for it.

Important fields:

It is important to have in mind that some fields in a Story are required and important to fill.

  1. Summary: a brief description about the objective and context of the work.
  2. Components: is a field that indicates the design team that will be responsible for the work.
  3. Initiative: sometimes a Story can be related or linked directly to a greater initiative.
  4. Priority: how important or urgent the work is at that moment.
  5. Assignee: the person who is going to be responsible for the work.
  6. Reporter: the person who had the initiative to ask or is requesting the work.
  7. Liferay Watchers: one or more stakeholders that will be informed over the Story updates.
  8. Due Date is the time limit or deadline for finish that specific work.
  9. Description: a more detailed text giving important information over the work to be done.
  10. Attachment: any imporant docuemnt should be attached to this issue.
  11. Labels: is a complementary way of organizing by topics or themes all the work that should be done.
  12. Epic Link should indicate the Epic that this piece of work is related to.
  13. Sprint: if the Epic is related to a team that works in running in sprints.
Something to improve? Report an issue!