Tips for Writing Effective User Stories: Approaches to Writing User Stories | Part 3 of 4
Receive free IIBA updates and exclusive content!
Questions about documenting requirements come up when talking about user stories. The myth of agile is that there are no requirement documents. Requirement details are still very necessary and, depending on the needs of your team, can be built into user stories or in artifacts linked to those stories. Tomette Kirk covers audience questions about handling requirements in this post.
Q: I am writing a lot of business requirements (BRD's) and would like to understand how user stories fit in. Do you only use user stories in an adaptive approach, or can I also use it in a predictive approach? Will the user stories replace the (long) business requirements with all the use cases or will you still need to write use cases?
A: The five-part requirement is useable for either a user story or a requirement, like you’d write in a BRD. I find it helps flesh out the details by including the ACTOR, DOES, THING, for a REASON. I use the five-part requirement in both environments: Agile (adaptive SDLC) and Waterfall (predictive SDLC). Long requirements are often not thoroughly read, so my preference is the shorter WHO? DOES? WHAT? WHY? then add details in the DONE WHEN?
The Use Case Template is common for predictive SDLC, but again, it leads to a lot of documentation that very few people read and digest. There is a place for use cases, but I usually only do them when a five-part requirement is highly complex and needs more description.
Q: What is a good practice for including high level design clarification in a user story? In the description? In an attachment?
A: Often, I will put a sentence after a User Story that says what the business wants. For example, “Business would like to see the report in an excel output.” Or “Business would like a dropdown option instead of a long list.” It’s a suggestion, but not a requirement, that can lead the designers toward designing what’s expected. However, they also may have a better idea for how to handle the request.
Q: What do you do when asked to build a mockup for a solution that is yet to be built and the User Story yet to be confirmed fully?
A: Mockups are great tools to explain what the user expects to see. Just remember that each section of the mockup should be represented by one or many User Stories, so the developers build something that works, and isn’t just on a screen. Mockups can help users define what they want, so work as a team and create them collaboratively. Just make sure they go hand in hand with a User Story. It’s a chicken/egg dilemma as to which comes first, the user story or the mockup, but in the end they should both be present.
Q: In Agile, are specifications built, do implementation details get documented or is that just the working software?
A: It depends on your development environment. If working with “offshore” (or non-collocated) teams, more detail may be needed. But usually, it’s more a try-something-out attempt, i.e., “working software.”
Q: Where are the non-functional requirements (NFR) captured?
A: NFR’s can be captured in three places:
- The WHAT section of the user story.
- The DONE WHEN sections of the user story (Acceptance Criteria are great places to capture details!).
- It's own story detailing the NFR.
Q: Is this a functional or non-functional requirement: “Website should accept more than 3,000 users to connect simultaneously?
A: This is typically a non-functional requirement of capacity. You can write it like you did, where the website (system) is the ACTOR, and it must allow X number of users to connect simultaneously without lag so that users do not experience long load times. “More than 3000” is vague – identify the tipping point of maximum users – 20,000 is more than 3000 but is a different requirement than 3000 - 5000 users.
Q: Is there a best practice on creating non-functional requirements as separate user stories versus within the acceptance criteria for business & functional user stories?
A: Most of the time I include the NFR’s in the WHAT or in the Acceptance Criteria. But if you think the effort for that NFR is significant, it may be worth splitting it to fit into a single sprint.
Q: Should I include requirement details like error message content, field names and type in user stories?
A: Whenever you can provide details, that’s great! What does the business expect to see? Do they have an idea for error message content? Field names? If they do, mention them! File type gets a little technical but is also negotiable with the end user. Write what they want, so they are more likely to get their needs and desires met.
Use this template to create user stories and acceptance criteria
Q: In the User Story scope definition is it okay to include some additional details such as properties of data attributes (data dictionary) or link to a file?
A: Sometimes you have to use attachments or links to another file to describe properties of data or calculations. Just make sure that you mention the additional file in the story, or the sentence after the story. Also, make sure the bulk of the explanation is carried by the story, probably in the Acceptance Criteria, and not just in the extra file, so that people know how to use the extra artifact.
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.
