A user story is a statement that’s structured “as a [role], I want to [action], so that I can [outcome]”, outlining the work you need to complete to meet the overall business requirement. The user story is the cornerstone of application development.
We have written over 1,000 user stories, released to production 77 times in the last 12 months, and deployed 439 user stories as a result (an average of 6.4 releases per month, 5.7 stories per release!)
As the Salesforce Admin of a rapidly growing ISV, I get a constant onslaught of requests for changes. Many of these requests come from people who understand Salesforce, and the request often comes with very specific ideas on how it should be implemented (a familiar story?)
Fortunately, in our organization, we have a very clear analysis process before we make changes. This ensures that we deliver what the user needs, not what they thought they wanted. Whilst this sounds like it would slow down delivery, in reality, it has proven to make it faster. We build the right thing, first time around.
What is a user story?
A user story is essentially a task, a piece of work you need to complete to help meet the overall business requirement.
A user story has a simple structure based on the standard agile format of “as a [role], I want to [action], so that I can [outcome]”.
Often a user story has acceptance criteria to guide the testing phase, used to assess if the requirement has truly been delivered. To prove that the delivered work meets the acceptance criteria, it’s typical to link out to supporting content, such as the process diagram, notes, and discussions.
All this goes together to then assess the risk that the user story will have across three dimensions; technical, operational, and regulatory. Following that, the user story is assigned to a release (more on this later).
User story vs. requirement – what are the differences?
A requirement is written from the business’ perspective detailing what the business actually needs – in other words, the desired business outcome.
Requirements are often written to very different levels of detail. They could be strategic, “we need to implement CPQ”, or tactical “We need to support a new customer type”, or “I want this multi-select picklist”.
The requirement is where (with your business analyst hat on), you want to get to the root problem. Over time, what I’ve found is that users are very good at coming to their admin with a ‘want’, however, the requirement is where you start to get to what the user actually needs.
User stories will be written from the perspective of a group of users to validate how the requirement will be relevant/suitable to a group of users. Ultimately, one or more user stories deliver the business requirement.
To summarize, at this point:
- The requirement is the headline for the desired business outcome, what the business actually needs, rather than wants.
- User stories help deliver the overall business requirement.
- User stories are the tasks required to deliver the changes to the systems.
Note: a user story doesn’t have to be related to a system change. A user story could detail a change to an operational process, or training content that has no impact on systems.
Write better user stories – the ‘5 Whys’ technique
The ‘5 Whys’ is a technique I’ve adopted when writing requirements and user stories. It’s as simple as asking ‘Why?’ until you get to the real root problem.
At first glance, this technique sounds like you’re being that annoying child in the back of the car asking ‘are we there yet?’ over and over again.
However, you will now have a defined business requirement, which means that you understand the ‘To-Be’ business process; this will help you to determine what user stories are required to deliver the new business outcome.
How a poorly written user story comes back to bites you
Poor user stories are born from not getting to really understand what is needed. They tend to be circular in their logic, for example, “As a Product Manager I want a Persona Object so that I can record Personas”. In other words, I want X so that I can do X.
Good, rigorous business analysis eliminates these types of user stories to eliminate system rework, and mitigate killing the agility of the business.
How to identify a poorly written user story
“Can you just?”
Poorly written user stories are often driven by these three words that sends shivers down every Salesforce Admin’s spine.
Sometimes the requests, at first glance, are low risk. They appear to be simple changes that can be done quickly. possibly straight into your production org. So, you write a user story with that bias and without the proper analysis.
Here’s a quick, real life example:
“Jack, can you just add a new stage to the opportunity stage field?”
I forgot my own rules, I wrote a user story for the change! I didn’t analyze any metadata. I thought ‘it’s a simple change, right?’
WRONG.
Turns out the stage field had 21 Flow dependencies, 7 Process Builders and 71 reports.
The poorly written user story and skipping the 5 mins of analysis, resulted in 2 hours of clean up.
I should have looked at something like a dependency tree (below) because it would have alerted me to the metadata items I needed to consider. It would have also given me the ammunition to push back on the requester, and show why it was not the simple change they thought.
Above: an example dependency tree for a field showing the related dependencies/metadata, and therefore, the knock-on impact any change to the field could have.
5 lessons we learned from writing 1000+ user stories
Lesson 1: Connect user stories with metadata
We already know that doing the impact analysis, and connecting metadata to user stories, helps you spot potential change conflicts early in the cycle.
Passing this information through to the development, test, and release teams means that they can plan and deliver their work more effectively. However, this is also building up the documentation for the metadata item that is so valuable for impact analysis, and cleaning up technical debt.
To illustrate this point, the image shows both the existing metadata, and proposed metadata added to a user story. Adding proposed items means we can add documentation to the metadata items before they exist in Salesforce. We know from experience that if we leave the documentation to “later”, it will never happen.
Above: user stories connected to supporting Salesforce metadata.
Lesson 2: Connect user stories with business information
A poorly written user story could have a huge impact on the Salesforce org (the ‘technical risk’ I’ve talked about until this point), but the user story could also have an impact on the business, namely:
- ‘Operational risk’, what changes are there to the business processes and training/enablement,
- ‘Regulatory risk’, which changes put the business at risk, from a compliance perspective?
The risks are quick to analyze if the user story is connected to business related information. This could be process diagrams, training content, screenshots, or compliance statements.
Again, this information connected to the user story is “documentation”.
Some of it is created automatically, where existing information can simply be linked. The documentation you add to the user story and metadata won’t help you now, but it certainly will the next time you touch the metadata, as it will dramatically reduce the impact assessment time.
Above: user stories connected to supporting information such as notes, images, and processes.
Lesson 3: Group user stories into releases
Every change, no matter how small, we deliver through a release. Remember we said we delivered 77 releases last year? A release is a grouping of user stories.
We look at the technical, business, and regulatory risks of the user stories when we group them into releases. Then we give the release an overall risk value which helps the development and test teams decide how, and how long the release will take to deliver – and deliver it with the minimum level of effort. If we know a release is low risk, then it could be put through a fast track with less testing (details in “Develop in Production to Accelerate Salesforce DevOps: A Guilty Pleasure Minus Any Comeback”)
We can also identify conflicts across releases. Is a user story going to be changed in multiple releases, and what is the impact? This becomes even more critical if you have multiple teams all working in the org where they may not have visibility of each other’s planned changes.
Without this visibility, they may only find out about the conflicts when they are pushed to Production, which is far more expensive and stressful to fix.
In those 77 Releases we have had 0 (zero) rollbacks.
Above: release conflicts for metadata in user stories.
Lesson 4: Sharing user stories with development (‘Shift Left”)
Development teams typically use a ticketing system to manage their work (Jira, Rally, Salesforce’s Agile Accelerator, etc.) The definition of the work to be completed will be the user story (although it may be called something else in the ticketing system).
The work put into analysis to create the user story, and all the supporting documentation, shouldn’t be lost when it is converted into a ticket. You will lose valuable business context that makes the ticket easier to develop and test, and reduces errors caused by any ambiguity.
A user story should automatically create a ticket once the user story reaches a key status; when the ticket is closed by development, then the status change needs to be reflected back into the user story.
Above: user story information shown in the right panel inside a Jira ticket.
Lesson 5: Build up documentation as a by-product of doing the analysis
Sharing is good. Re-keying is bad. Not knowing is worse.
The analysis, risk assessment and documentation is valuable around the entire implementation lifecycle.
No one has time to document properly, even though the benefits are clear. The problem is these benefits are only felt later.
So this user story approach I have described builds up the documentation as a by-product of doing the analysis, quickly.
Making the connections between user stories, business process diagrams, notes and metadata will accelerate future analysis and development – the flywheel effect. You already have the complete history of changes to the metadata, and why they were made, which in turn, makes the analysis quicker, development faster, and less risky.
Next steps
This approach sounds amazing, but it must be hard to implement? Not really. You don’t need to completely reinvent your development processes. You can try it for the next piece of work you are delivering by taking these steps:
- Centralize the capture of the user stories.
- Commit to doing analysis on every user story before it is passed to the development team..
- Link user stories to metadata and any other supporting information.
- Provide access to the user story and linked information to the development team.
Comments: