The Art of writing a User Story to ensure Successful Delivery

This event for business architects originally took place on Tuesday, October 28, 2022.

Join the conversation and find related content for this event on the Pega Support Center post!

Description: This webinar covered how to strike a balance between human-readability and engineering readiness in user story development. Expect best practices, numerous examples, and a discussion of common pitfalls.

We hope you understand we couldn't get to every question during our Q&A session, but we'd like to provide answers to as many as we can.

Check them out below:

My product owner struggles to keep track of all the user stories and how they relate to each other   - what do you recommend we include in the stories to address this? 

This is a frequent problem on most projects.  There are many ways to address the issue depending on the nature of your project. Where you are recording your stories outside of Pega in a separate backlog tool, an effective way to maintain an overview is to draft the end-to-end process within a collaboration tool and link the relevant stories visually to the steps in the process. This helps to reflect the user story flow more easily.  If you are using APP Studio and Agile workbench you can link your user stories directly to the build.  Agile workbench also allows for the user stories to be grouped by feature. For Pega versions 8.4 and beyond, App Studio’s visual display of the steps and stages ensures the entire team keeps the end-to-end process in mind when defining and building out the user stories. 

What do you mean by In-sprint test and high priority ?

Broadly speaking, High Priority issues identified during the sprint are to do with acceptance criteria of a story not met completely or partially. If acceptance criteria are not met completely, it is safe to classify them as high priority defects. At times, things get blurred when acceptance criteria are very loosely documented and can be interpreted in multiple ways or may extend training into areas outside of development done.  In both these situations, it is eventually the PO’s decision to categorize the priority of the observation and it is agreed with development to either address it in the current sprint (normally based on efforts) or move to the next sprint.   

Would like to share these slides with others on my team - will they be distributed? 

Yes, these slides are available as a PDF document.   Please refer to the link below and ensure you are logged into the collaboration center.   

While writing the user stories, I end up making them very short. I am not sure if it's a good thing or bad. I go with what we need to do followed by why or how does this helps. What am I missing? I also need to understand how to build acceptance criteria. 

Hopefully, the content of the webinar helped to directly answer your question in more detail.  To summarise, at Pega we advocate the best practice for the user story description is to follow the Who, What, Why format.   This ensures the user story is centered on the persona’s needs as well as the value achieved by addressing the need. User stories do not need to be long, but they do need to be clear, easy to read, and most importantly testable.    

We have some great guidance on what good looks like for user stories in our Pega Express Delivery mission on Pega Academy and we also have a useful document on our Pega Express Toolkit 

How do you write a user story for a BOT? 

A bot serves a business purpose, it automates a task that we might have needed a person to do in the past. Like any automation we want, approach this from the point of view of the persona it is benefiting. So write your user story with this benefit in mind, for example 

As a Registration Lead, I want the system to automatically update our core system so I do not have to manually rekey all the information. 

Acceptance criteria 

1. A customer master record is created in system 1 

2. This information is copied into system 2 (see attached for property mapping) 

Often our product owner and our other IT teams want detailed requirements and technical documentation to be included in the user story. How do you handle such scenarios? 

One of the first activities the project team should cover at the start of the project is to define and agree on the Definition of Ready.  This lists the project team requirements for a story to be eligible for sprint planning and by default defines the minimum information required within a user story.   The discussion to agree on the Definition of Ready is a good opportunity to determine what and how additional information required by wider stakeholders may be supplied. It is important that during the discussions the benefits of user stories are not undermined by overloading them with enterprise-level information. It is worth separating the enterprise-level documentation from the user stories - so that it is easy to access and consume by the relevant stakeholder groups and crucially lives beyond the sprint cadence. 

Can I understand as Persona + Need + Purpose = Human-centric ?

Spot on, yes – Persona + Need +Purpose puts Human centricity at the core of the discussion. If we extend ‘Purpose’ a bit more and add the ‘Business Value’ or plainly put ‘Persona Value’ into the dimension we add a bit more perspective to the conversation. The value that each story brings to the persona helps in making sure that the highest business value is always the highest priority within the delivery. 

Is there any rule that the user story should be long or short? or it depends on the agreement of the team? 

User stories should be as succinct as possible.  Following our best practice guidelines for the user story description and acceptance criteria will help you keep your user stories to an optimal length.  The key purpose of the user story is to covey the needs and the outcomes required by the persona so that all team members from the business team through the build and test team are clear on the expectations and the success criteria.  Each team will have different information needs – so yes the team must agree on the definition of optimal for user stories – and this should be agreed in the Definition of Ready.    

Where does the design thinking practice come in the entire User Story life cycle? 

Design thinking is present through all the activities up to the point of User Story Approval.   By this point, the user story should be drafted and refined with results from any design thinking activities included as part of the user story content. 

Our testing team requires that we have very detailed acceptance criteria - sometimes I've had to list each step in the process with the success and failure conditions which mean I have had nearly 20 acceptance criteria in a user story.  What do you recommend for this situation? 

A common mistake is to translate the acceptance criteria into test cases and pseudo test scripts.   The purpose of the acceptance criteria is to ensure that all the relevant outcomes are achieved by the user story.  The number and nature of test cases that need to be addressed to ensure that the outcomes are fully addressed need to be agreed upon with the tester during the refinement process.  These documents should be attached to the user story as part of the supplementary documentation before the user story is considered eligible for sizing and sprint planning. 

What about DOR for stories? 

Absolutely, we agree with you.  As part of our delivery approach – we strongly recommend that the team ( I.e. the product owner, system architects, business architects, user experience architects, testers) collaborate on defining the Definition of Ready.  

Our Pega Express delivery approach makes provision for these conversations during the Prepare phase.  This means that right from the start of the project the team is aligned on the minimum requirements from the perspective of both the business and the technical teams. 

Without being explicit about the how ("Press the submit button"), how do you ensure consistency in implementation across the solution?  How to avoid different developers implementing in different ways, negatively impacting user experience? 

At Pega, we strongly advise that the UX design patterns are established in conjunction with your UX leads on the project.   Using our Cosmos Design system out of the box will also help to ensure consistency.  Where you are not able to do this – we advise that the UX is discussed with the technical team as part of the user story refinement.   Any additional documents to support the technical team, for example, wireframes can help to ensure the technical team understands the UX design pattern that needs to be implemented.   

Sometimes once we have started building the story we identify a key aspect of the requirements and the design that we have missed.   My PO wants me to add the missing elements to the story so that the functionality can be delivered in the current sprint, but my technical team says that we need to add a new story for the next sprint?   What is your recommendation for this situation? 

Strictly speaking - once a story has been added to a sprint - the scrum team has agreed on the scope and size of the story and as such it should not be changed. Changes at this point make it difficult to record the team's true velocity and risk the delivery of the remaining stories in the sprint.  There are occasions however where there may be documentary changes to the story that helps with clarity.  Where those changes have no bearing on the scope and/or design of the build – it is pragmatic to ensure the latest understanding is recorded.   

For those occasions where the miss in the user story is such that affects the scope/design two options prevail, the story can be withdrawn from the sprint to prevent unnecessary rework in the next sprint, or the story can be built within the current sprint and the additional features added by way of a separate story(s) in later sprints.  In both instances, a conversation must be held between the system architect, business architect, and the product owner to ensure the appropriate decision is taken.   To keep the velocity consistent, you can agree with your product owner on stories that can be taken out of the sprint and others added.  This must be done with caution and in collaboration with the build team. 

Do you recommend any tools for UX UI  ?

For those projects that are being delivered on Pega platform v8.4 and above we recommend that prototyping takes place in App Studio.  This helps to ensure that as many out-of-the-box UI features are used within your UX and UI design.  For some more information on standard design patterns, try our Cosmos Community Page 

Who authors the technical details? 

We would expect the technical team ( system architects ) to author the technical documentation associated with user stories. 

As mentioned by Shubhi, there is a lot of impetus on "conversation" within the scrum team during the Sprint to make sure the story is built correctly as a lot of granular details are shared and discussed outside of the story's acceptance criteria. When an application goes into UAT and then later into production, this conversational information is either lost or is scattered across comments on the story in Agile Studio. How do you make sure this information is not lost and available at later stages? 

The ‘‘conversation’’ within the scrum team is indeed one of the most important pieces of information used across the teams( Business Architects, System Architects, Testers etc )  during the delivery lifecycle. As also mentioned in the webinar, all the important conversations behind the story should be added to the story as supplement information. A lot of times, the conversation might lead to updating the process flow that describes the entire narrative or microjourneysTM. This will ensure that while this supplement information is available in the context of stories, but the overall information at the end of the delivery to support the UAT /Production is always current.  

When I joined the project my customer had a detailed requirements document and wanted to map the stories to the requirements.  This was a lot of work and it was difficult to maintain.  How would recommend we address this situation again? 

It is the responsibility of the product owner to ensure that the backlog and the user stories therein reflect the business requirements and are prioritized accordingly.  With this in mind - where the business teams have spent time preparing the groundwork for this by creating dedicated requirements documents - the product owner can elect to update that document with the user story reference numbers as they are created and evolved to ensure they have a record for themselves of the traceability to their original thinking. 

My technical team insists I provide a data dictionary detailing every aspect of the screen design and development.   Is this really for the BA to do? 

Commonly, the data elements should be included in the user story along with mock-ups to reflect the user interface design.  To this end, the user story should include documentation that defines the data elements in business terms which includes the mandatory and limiting behaviour expectations ( i.e. valid values, validation rules, etc).   This is well within the domain of the BA.    

Where there is a need to share the internal property identifies then this is best supported by the technical team.  Ideally, if there is a need to have an ongoing document for external parties to access then is more efficient to have a centralized enterprise data dictionary.  The ownership and change control of the document must be agreed upon to ensure it maintains integrity.  This should be set up early in the project so that the data dictionary can evolve and expand incrementally sprint for the sprint as the project progresses.  

It is worth remembering that for projects running on v 8.4 and beyond, App Studio offers a great visual reference of the data objects and their association to the case types which could negate the need for external documents. 

My technical team insists that I as the BA right the user stories for the interfaces - My PO has no understanding of these user stories and can't sign them off - how do you suggest this functionality be documented? 

Whilst interfaces may seem like a technical requirement and therefore covered by the technical team, there are many business implications to consider when systems interface.  It is important that the business be encouraged to consider the acceptance and rejection scenarios that need to be accounted for by the processes using those interface points.   It is appropriate for the Business Architect to draft user stories in business terms to address the requirements and the behaviour of the system integration in outcome terms.