Tips for Writing Effective User Stories: Approaches to Writing User Stories | Part 1 of 2
Receive free IIBA updates and exclusive content!
In the first post of this series, Tomette answered Member questions regarding the approach to writing user stories.
User stories have a common structure but there are many details that the development team will need that don’t have a natural home in that structure. Tomette covered many tips for including those details in the story format so requirements can trace to the story implementing it.
In this post, she answers questions on the format, structure and content of user stories that will ensure they contain the information they need. For the full context behind these questions and to hear Tomette’s tips firsthand, watch her talk on Writing Effective User Stories.
Q: What are your thoughts on Gherkin syntax?
Gherkin is a method for writing user tests that was developed from behavior driven development. The format is Given-When-Then, where a scenario and its expected behaviors and outcomes are documented. It is sometimes used to document Acceptance Criteria. Gherkin is helpful for getting a context, but difficult to read and digest for testing scenarios. I prefer the more straightforward “Done When” approach for Acceptance Criteria. Remember, people do not read long paragraphs of text. Work to simplify the words. .
Q: When should you add descriptions for the Actor?
A: It is perfectly acceptable to add descriptions to the actor. There was an example in the webinar, “As a consumer who is enrolling, I…” Descriptions are good, just as long as they don’t become convoluted and take away from the very direct Actor-Does-Thing. Preserve that simplicity whenever possible.
Q: If two roles have the same need, do we create an identical user story for each user?
A: Say, for example, you have a Customer Service Rep, an Admin, and a Supervisor that will all have the same functionality. It might be ok to say, “As a CSR System User, I…” but then I would call out three separate scenarios in the Acceptance Criteria for testing each security level.
Done when: A customer service rep can update demographic data.
Done when: An Admin can update demographic data.
Done when: A supervisor can update demographic data.
The reason for this is that they all can’t be tested at the same time and would need to be tested separately per role. General rule is: if it can be built together AND tested together, it could be in one user story. If it can’t, then they should be separate stories. It’s rare when they’re combined.
Q: When there are multiple users (e.g. multiple teams) which are asking for the same user stories can you have multiple actors?
A: Multiple teams can work the same story using tasks underneath the story. However, multiple “actors” are not best practice. Single actor, single action, single outcome (Who/Does/What) should be your goal for a user story.
Q: Does using "and" in any part of a user story indicate that the story should be split into multiple user stories; or is your user story simply too broad?
A: Singularity in the Actor – Does – Thing, is the key. Very rarely are two or more actors doing the exact same thing that can be built and tested together. Where there is independence needed for the Actor/Action/Outcome, write separate stories. Common things to look for: And, Or, and / (slash) are common culprits of multiplicity.
Q: When you are writing user stories, how do you decide how descriptive and in-depth are they going to be?
A: Two points: try to write the description (Who Does What Why) simply so that people can read and digest it. Too lengthy verbiage in a user story causes readers to glaze over. Second, use your Acceptance Criteria to include the details. With that being said, make sure all the AC can be accomplished in a sprint, both built and tested. If you find you are getting a long list of AC, you may need to split the story to be accomplishable in a single sprint.
Q: Can we also write / mention alternative / exceptional flows while drafting user stories?
A: Negative Acceptance criteria are a great place to put alternate flows. Done when: If <X (exception)> happens, then <Y> takes place. This allows for alternate builds and negative testing to occur. This can get cumbersome to account for ALL exceptions, so monitor when you need to split the stories.
Q: Where do you save intricate details, such as the specific formulas used, the specific field UI labels to use, the specific text to use in the various user messages/alerts needed, etc...)? If those fine details aren't written down very specifically, everyone is confused: the developer doesn't know what to code, the QA doesn't know what are the expected results, the implementer doesn't understand how the values are calculated, etc.
A: I have seen specifications placed in the Acceptance Criteria (the Done When section). But user stories are generally not detailed specification requirements. This type of documentation may need to accompany the user story in a mockup or a spreadsheet with calculation. It is very hard to communicate the intricate details in a user story, especially when teams aren’t collocated. You might want to use an SRD (Specifications Requirements Document) in these instances, along with or instead of a user story.
Q: In the ' Done When...’ can you indicate if some of the items are higher priority than others, some are must have, and some are optional or lower priority?
A: MoSCoW is a great tool for prioritization: Must have, Should have, Could have, Won’t have, or High, Med, Low, Out of Scope. You can use H,M,L. But in a true user story, all of the functionality within it is needed. It’s more common to prioritize stories than to prioritize Acceptance Criteria. If you have Med or Low AC, think about breaking them out into a “Nice to Have” story for later release.
Q: Should acceptance criteria hold design details?
A: There can be some design details in the AC, but I prefer to mention them as a “suggestion from the customer” instead of the way it HAS to be. For example:
Done when: The report is in an Excel format. OR
Done when: The report can be read using Excel (this is the customer’s preference). [This can imply that it could be a .csv file or pipe-delimited file, but the customer can upload it in Excel.] OR
Done when: The report can be uploaded. (The customer prefers that the report is viewable in Excel.) [The pass/fail test is that it can/cannot be uploaded. Maybe it’s uploaded to a UI and can be exported to Excel. The customer’s preference is that it’s viewable in Excel, but that is just a suggestion.]
Q: Are there any other elements of the user stories: other than description and acceptance criteria?
A: What does your team need? If there are other elements that are helpful to the team, include them in your template.
IIBA Members, login to watch the Writing Effective User Stories webinar on-demand. Stay tuned to IIBA’s Analyst Catalyst blog for the next post in the series, where we’ll dive into dealing with user story format and structure.
Only IIBA Membership gives you exclusive access to IIBA’s KnowledgeHub. If you are not yet a Member, join today to become a Member of IIBA and start experiencing all the benefits.
About The Author:
Susan Moore is the Community Engagement Manager at the International Institute of Business Analysis (IIBA). She is a Product Management professional with more than 20 years’ experience in the Finance and Insurance industries. Before coming to IIBA, Susan worked in Business Analysis and Project Management roles, incorporating business analysis leadership and agile practices into the business analysis teams where she worked. Susan also writes on these topics at TheVirtualBACoach.com. Susan holds several business analysis and Agile certifications including IIBA’s Agile Analysis Certification.
