Skip to main content

User story readiness

User story description

A user story describes how an end user uses an application to achieve a specific outcome. It is a human-centric way to document a business requirement in a simple and concise format. A user story represents the smallest unit of work to be developed within the application.  

The primary purpose of user stories as project artifacts is to help the development team keep track (within the project backlog) of all the features they need to build and implement for the client. User stories describe what is required so that features can be designed to satisfy the Product Owner's satisfaction and, ultimately, the end business user. A team creates a user story with the team's collective knowledge and experience. 

The key features of a user story:

  • Human-centric
  • Easy to understand
  • Clearly reflects the business value the client receives
  • Can be tested

User story structure

You begin by documenting two important elements in a user story. The elements provide clarity on what must be developed and what criteria must be met to consider the user story complete.   

The two elements are:

  • User story description
  • Acceptance criteria 

You also add optional elements to each user story to clarify the details of the requirement with attachments and technical notes. 

All stories have a size and status to help with user story management. You update these as the user story progresses through its life cycle from the initial form to its completion.

User story description

The purpose of the user story description is to summarize the client's business requirements. The user story description ensures you capture who needs the feature or function, what is needed, and why it is needed. It needs to be short, written in business language that is easy to understand, and clearly identifies the business value.  

The typical phrasing of a user story follows a simple sentence format;

  • As a… [Who? - Insert the user]  
  • I want… [What? - Insert what they want to do]    
  • so that… [Why? – Insert the Business Value]

The preparation and discussions behind user stories are extremely important.  You can only gain this collective understanding through dialog. Resist the temptation to translate the collective understanding into complex documentation. Focus on the essence of the user story, and supplement the details with attachments.

Tip: Make sure the user story description is not written in technical terms; this gives your technical team the creativity to use the best out-of-the-box features to configure a solution. 

In the following example, the description is written in business terms that clearly state the user, the need, and the business value of implementing the user story. You will also see that the description is brief.

 

user story description
Tip: Give each user story a brief name to summarize the content, such as View promotion results or Register new user. Doing so makes it easier to find user stories in the backlog. 

 

User story acceptance criteria

The acceptance criteria refine the user story so that developers understand what the application must do, and testers are clear on what needs to be tested. The Product Owner is required to define the business experience expected from the user story and approve the acceptance criteria. User story acceptance criteria are written in unambiguous terms that are easy for the business (and non-technical team members) to understand. 

Acceptance criteria are written in outcome terms, and not as technical instructions to the development team. They are deliberately negotiable, allowing the development team room to work with the business to achieve the solution. Acceptance criteria, while negotiable, must also be specific enough to test. 

In the following example, the acceptance criteria are written as outcomes that are specific and testable.

User story acceptance criteria

 

Note: Acceptance criteria can describe the system behavior that should happen and any outcomes that must not happen. For example, an outcome that may not happen is: The user may not proceed until all mandatory data has been captured.

 

The sample user story illustrates a statement approach to phrasing your acceptance criteria. There are a variety of other styles for documenting acceptance criteria, such as capturing scenario-based criteria. For example, your team may choose to use the Given, When, Then approach formatted as follows:

  • Given...{pre-condition}: Example: "A premium member is eligible for free offer promotions..."
  • When...{something is done}. Example: "...they have selected their preferred offer categories and completed the registration process..."
  • Then{expected result} Example: "...the system will automatically add the member to the selected upcoming promotions."
Tip: Limit your acceptance criteria to 6-9 items. Too many items may indicate that a user story is too big or complex. If you have 10 or more criteria, consider breaking your user story into multiple, smaller user stories. 

 

Definition of Ready (DoR)

At the start of the project, your team defines what is meant by Definition of Ready (DoR). The team agrees on the DoR during the Prepare phase to set the baseline for user story quality checks. Each project reaches this agreement with relevant business and technical stakeholders on the team. The DoR lists criteria you must meet before a user story is ready to build. Once your user story is ready according to the DoR, you can mark the story as eligible for sprint planning. 

Typically, the DoR is a checklist of criteria. The criteria define the content that must be present in the story, any review process, or signoffs that must have taken place, as well as any artifacts that need to be gathered or attached. The following spreadsheet shows a user story with 12 example criteria to meet.

Definition of Ready

A predefined DoR ensures that all team members are clear on the minimum requirements for a user story. It confirms that any user stories placed into a sprint have undergone a quality check and can be successfully delivered within the sprint.

Tip: You can find a sample Definition of Ready Template on the Pega Express toolkit page.

User story refinement

The purpose of refining a user story is to ensure that your team has a complete understanding of the intent and scope. Story refinement is an iterative process that matures the story content  to meet the definition of ready. The Pega Express delivery approach promotes Direct Capture of Objectives (DCO) to ensure collaboration with all relevant stakeholders. DCO is used throughout the refining process to ensure each user story has all the information included in it, from all points of view. 

User story refinement begins with a draft story that may include little more than a brief description. Refinement ends when you hand the user story to the technical team for sizing. 

Draft user stories

The Business Architect, Product Owner, and other relevant stakeholders discuss the user story so that business objectives and user requirements are clear. Once done, the stakeholders share the user story with the technical team for further refinement.

Refinement

The business and technical teams work together. This collaboration includes the Product Owner, subject matter experts (SMEs), UX design specialists, testing specialists, business architects, system architects, and IT specialists. The teams review the user story and clarify the details. User story refinement may take several DCO sessions before the team is satisfied that the user story has been discussed in detail and documented appropriately. 

Depending on the nature of the user story, you may need to add artifacts like: 

  • User story approval emails
  • UI wireframes
  • Process maps, business rules
  • Decision logic diagrams

As part of the refinement sessions, the technical team interprets the acceptance criteria and translates the outcomes into components that need to be configured within the application. The technical team also identifies any dependencies the story may have on other user stories and impacts the story may have on existing functionality and areas of particular complexity.

The technical team may need to take account of non-functional requirements, such as specific user accessibility requirements. These requirements may be lost if not documented within the user story. During refinement, the team documents those details in the user story through additional attachments or specific acceptance criteria. 

As you refine the user story, you may realize it is too big or complex. In that case, break it out into more than one user story.  Alternatively, your work during refinement may expose a gap in the requirements and generate the need to add additional user stories to your backlog.

Once stories are refined

The refinement process ends when:

  • The team agrees that they understand the user story
  • All the additional supporting information is added to the user story
  • The Product Owner approves the acceptance criteria  

Once refined, the technical team is in a position to size the user story. The story sizing brings the refinement to an end.

Technical stories

As part of the refinement process, the technical team identifies technical tasks to complete that fulfill the acceptance criteria of a user story. Some technical configurations warrant special attention. The team can separate these tasks from the configuration effort. To facilitate the allocation of work within Scrum and ensure that reusable components are built with the appropriate acceptance criteria, the scrum team may decide to create a technical story that includes only technical elements.  

Typical examples of technical stories include:

  • The configuration of interface connectors
  • Test harnesses
  • A DevOps repository
  • New environments
  • Other technical elements required to support multiple user stories

During refinement, the technical story is listed as a dependency for any user stories that require these generic technical components. Technical stories allow team members to work in parallel to deliver related user stories in the same sprint. The team also separates the effort associated with creating technical assets from that of creating business solutions.

Technical stories are subject to the same rules as user stories to the extent that:

  • They must meet the definition of ready to be allocated to a sprint
  • They are sized in the same way non-technical user stories are sized

Story sizing

There are several ways to reflect the size of a story. Story pointing (giving points to each story) is an activity conducted at the end of the refinement discussion. The purpose of the activity is to size the story's complexity. The higher the number, the greater the story complexity, and the higher the effort to configure, test, and implement the story. A common approach is to use the Fibonacci number sequence. This sequence allows the team to rank stories in terms of relative complexity.

The following Fibonacci scale determines story points:

  • 1 Story Points = Very Small Story
  • 2 Story Points = Small
  • 3 Story Points = Medium
  • 5 Story Points = Medium to Large
  • 8 Story Points = Large
  • 13 Story Points = Very Large
  • 21 plus Story Points =  the story needs to be considered as an EPIC and broken down into smaller pieces.

Estimation with complexity buckets

Achieving a consistent evaluation of story complexity can be challenging as each team member may view complexity differently. You can estimate story complexity using complexity buckets to give your team a way to size stories consistently by discussing each story in terms of predefined buckets of complexity before choosing the final points.   

During the Prepare phase, the team must agree on the criteria most appropriate to evaluate the story's complexity. Each criterion becomes a complexity bucket. Within each bucket, the team must agree on a ranking of complexity from Light, through Medium to High or Complex. For example, developers should consider the UI implications of the user story, the amount of testing, configuration, number of business rules, and data integrations as they decide upon their sizing number. For each level of complexity, you assign a point value

Typical complexity buckets may include:

  • User interface
  • Business logic 
  • Data
  • Integration aspects
  • Testing   

During the sizing session, the team reviews each story against all the criteria and calculates the total story points based on each category's complexity rating. The total value is then matched to the appropriate Fibonacci number. Where the numbers are not an exact match and fall between the sequence of the Fibonacci numbers, the team agrees which of the Fibonacci numbers on either side of the total best represents the complexity and assigns that value to the story.

Complexity Buckets

Once a user story is estimated, it is now ready for consideration by the Project Owner at the next Sprint Planning session. 

Tip: Play Planning Poker. Planning poker is a collaborative approach to get agreement from your team members on the size of a story. You start by discussing the story with the team to assess it for complexity. Each team member then provides their estimate of the story points. Team members discuss their different estimates, and the team repeats the process of sizing. When all members agree on the story points, you can allocate the number of points agreed upon to that user story. 

What good looks like

One of the most common questions on an Agile project is, "What does a good user story look like?" There is no one size fits all model of a user story; the model is different for every team. A range of experiences and industry backgrounds influence the collective requirements of the user story.   

The following example reflects what a good story would look like once fully elaborated, refined with the technical team, reviewed against the definition of done, and declared ready to build. In the example, look for the following elements:

  • Story name
  • Description 
  • Acceptance criteria
  • Story size  
  • Story status
  • Additional information 
User Story

 

Note: Your user stories improve as your team matures together, which may mean less documentation is required. Alternatively, lessons learned from issues you discover in a sprint can be incorporated into your team's processes to help create better user stories. Be flexible and ready to adopt updates to your user stories to ensure that they meet their primary purpose: to help the development team implement an application that satisfies the Product Owner, and ultimately the end business user.

Check your knowledge with the following interaction.

    If you are having problems with your training, please review the Pega Academy Support FAQs.

    Did you find this content helpful?

    100% found this content useful

    Want to help us improve this content?

    We'd prefer it if you saw us at our best.

    Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

    Close Deprecation Notice