Why do REs write user stories? That is an excellent question. The answer is that in some circumstances the scope of requirement elicitation is greater than the benefit of collecting and writing shall statement requirements, or a process can be captured in ways more accessible to the users who need to validate the requirements.
For example, I have seen cases in which a simple function was used by many users across many groups in an organization. Rather than spending countless hours interviewing different user types from various groups, it proved more effective and efficient to write stories about how the stakeholders used the function.
In such cases, we are able to craft statements that users would understand better and also employ a more flexible approach that fit better with an agile development methodology. User stories provide a more streamlined and flexible approach to requirements that enable teams to manage the development effort in a much more dynamic environment.
In this chapter, you will learn more about what user stories are, their benefits, and how you can use them to supplement or replace traditional requirements.
Anatomy of a User Story
First, you will examine the parts of a good user story. Then, you will learn the six attributes of a good user story and look at each of the attributes in detail.
Parts of a User Story
What does a user story consist of? The previous chapter presented that a user story follows this type of template :
“As a <role>, I want <function/feature> so that <benefit>.”
Or this type:
“As a <who>, I want <what> so that <why>.”
Simple, right? Well yes, and no. In theory, it sounds simple like most theories do. Of course, it is. In fact, that is the whole point of a good user story is to be simple. Naturally, the challenge occurs when you write them. Now, examine what the three parts of the story are.
The <role> is the person, the people, or even a system, application, or service that is doing or affected by this, also known as <who>. For example, “As a taxpayer submitting my taxes, ….”
Here are some examples:
As a search user, …
As a system administrator, …
As an HR user, …
As a payroll user, …
As a report reader, … (you do not need to say user every time, as in the earlier system administrator case)
As a workstation user, …
As a radiation dosimetry user, …
You want to be as specific as is practical. Break down the user to the particular role that they are doing. Do not just say, “As a user, …” as that is not specific at all.
The <function/feature> is the action the <role/who> needs. Clearly, this is the most important aspect of the story of the three. This describes <what> is wanted. For example, “As a taxpayer submitting my taxes, I want the 1040 form instructions written to a fifth-grade reading level …”
Here are some examples:
… I want to query records…
… I want to display query results…
… I want to sort query results…
… I want to filter query results…
… I want to print query results…
… I want to capture radiation exposure readings…
… I want to read radiation exposure readings…
Again, you want to define this down to the lowest level of the function as possible. You will see more about this shortly.
The <benefit > is the benefit the user will achieve with this <function/feature>. You want to know <why> the user wants this user story.
Here are some examples:
… so that I can access data.
… so that I can display data.
… so that I can print data.
… so that I can generate reports in the format I want.
… so that I gather the radiation exposure data of soldiers in the nuclear battlefield.
You can see this is one aspect that the shall statement did not provide, the reason why this user story should be done. This goes a long way in helping the users and stakeholders to understand the benefits of the current or new system.
Then, put all three parts together and you get this example:
13-1 As a taxpayer submitting my taxes, I want the form instructions written to a fifth-grade reading level so that 99% of the taxpayers will understand what they are filling out on the form.
While this type of user story is unlikely to happen soon (think of the run-up to April 15 every year), this is just an example. Think about this user story, whether it meets the criteria of a good user story, and you can examine it at the end of the chapter. Here is another one:
13-2 As a cell phone user, I want to retain a list of phone numbers selectively that I have received so that I can choose which numbers I want to reuse later.
Notice how easy it is to read? That is a significant benefit for users and stakeholders to understand them. This is an advantage to the user who can understand user stories even better than shall statements. User stories work well with the agile methodology. The user story and subordinate acceptance criteria can be refined as the user story approaches the sprint where the story will be implemented. This approach of writing user stories near the time they are implemented helps to negate the effect of requirements scope creep, unlike in the waterfall approach where you must create all the requirements (whether shall statements or user stories) up front.
Here are a few more examples to consider:
13-3 As a person logging onto BOSS, I want to have three tries to get my login ID and password correct before the system rejects my login attempts so that one or two mistakes do not punish me.
13-4 As a bike rider, I want the push on the hand brake so that when I need to stop, the bike will respond.
As you can see, you can write user stories for both hardware (bikes) and software (logins).
Attributes of a User Story
Just as there was a section defining what made a good requirement, there are attributes of a good user story. Bill Wake coined the acronym INVEST to describe those attributes. Here is what INVEST stands for:
Independent
Negotiable
Valuable
Estimable
Small
Testable
Now, consider each one of these attributes of a good user stories.
Independent
Independent means that a story can be developed, tested, and even delivered on its own. You want to write a story so that it can stand on its own. Here are some examples:
13-5 As s soldier in a nuclear battlefield, I want a way to collect radiation exposure levels so that my unit and I will know my exposure in order to manage my exposure levels both militarily and medically.
13-6 As an FBI Records Manager, I want to be able to view any record so that when I need to examine it, I can.
You might wonder whether each of these stands by themselves, making them truly independent. In these cases, and for many of the user stories you write, they may not be purely independent. So, what is a requirements engineer to do?
Not to worry. Almost every story you write should be able to have some independence. Think of the viewing the record story shown user story 13-6. You cannot view a record if it does not yet exist in some repository, and then if you query it, you need to be able to do so. You probably won’t get just one record, but a listing of them. You may have many other functions such as printing, sorting, filtering, exporting, and so on, that you might want to do. That does not mean you cannot write it the way it was presented earlier. You just need to write each of those other functions as separate user stories. Therefore, you could have the following:
13-7 As an FBI Records Manager, I want to be able to view a listing of records I requested so that when I need to examine them, I can.
13-8 As an FBI Records Manager, I want to be able to print a listing of records I requested so that when I need to examine them, I can.
13-9 As an FBI Records Manager, I want to be able to sort a listing of records I requested so that I can organize them the way I want them.
13-10 As an FBI Records Manager, I want to be able to filter a listing of records I requested so that I can organize them the way I want them.
13-11 As an FBI Records Manager, I want to be able to export a listing of records I requested so that I use them outside the application.
You may need to have more functions, but you get the idea. Granted, you would not see all the search-related function at once. However, each user story here should allow the developers to produce something that they could demonstrate at the end of the sprint, which is the goal of the user story and the associated user stories for that sprint.
You need to consider the same process for the radiation dosimetry project where you might have the following:
13-12 As a soldier in a nuclear battlefield, I want a way to determine how much radiation exposure I have received so that my unit and I will capture my exposure.
You may think of more user stories also, like reporting of the entire unit, and so on.
One advantage to having the user stories independent of each other is that you can move them around, execute them in different sprints, or keep some on the backlog for a while. That flexibility is the primary purpose of user stories, and independence allows that to occur.
If two user stories seem very tightly coupled, that means they probably depend on each other and probably belong in one user story. Of course, you still need the story to be small, which will be talked about later in the chapter.
Remember in Chapter 2, the I meant implementation independent. Does it still mean that here too? Absolutely. Many sources may not say that, but it is still true here. Granted, it is a goal, but follow it just like you do in shall statements for the same reason, so you do not restrict the developers, allowing them to do what they are best at—develop.
Negotiable
Unlike in requirements development in the waterfall methodology, as you have seen earlier in the book, that remain fixed once they are captured, a group of user stories is not a contract etched in stone. You can discuss, develop, refine, update, and even reject a story as time passes. You negotiate a user story with stakeholders until all parties affected, including the development team, are satisfied with the definition.
Once a story goes on the backlog, this negotiation process can occur at any time while it resides there. This is because as the user story gets closer to being designed and developed, all parties have the ability to learn more about the story and define the needed details.
This provides one of the best advantages of the user stories—flexibility. Remember how the waterfall requirements collection “froze” the requirements until delivery? Remember how the biggest drawback of that is the one or more percent requirements changes per month? By negotiating the user stories as they become close to being developed, you help to eliminate that scope creep because you reevaluate each user story and update it as appropriate with what you know at that time, rather than waiting months or even years as in the waterfall method. Think of this as just-in-time requirements definition. By crafting user stories (or reviewing and revising previously written ones), you capture the need precisely when you need it, and your understanding of the requirements is current. That 1 to 4 percent requirements change per month is eliminated. This is a major success for this agile approach.
Thus, the negotiation can come at multiple times until just before the story is worked on during a sprint. For example, early on a user story may look like this initially as a placeholder:
13-13 As an FBI Records Manager, I want to be able to delete a temporary record from the repository so that records I am no longer required to retain can be deleted.
Six months later, the stakeholders and you revisit this story the month before the developers will work on the story during the upcoming sprint. You meet with the users and stakeholders (or use a technique or techniques discussed in Chapter 9), and after you presented the story and asked if this is still correct, the record manager stakeholders have clarified it as follows:
13-14 As an FBI Records Manager, I want to be able to delete a temporary record from the repository in accordance with the records retention schedule prescribed by National Archives and Records Administration (NARA)so that records I am no longer required to retain can be deleted.
Note
The bold text is what was added. This points out the use of techniques to highlight changes. Microsoft Word has the Track Changes capability that can be useful. It is good to show what is added, deleted, and changed. If that is not practical, maybe you should show the before and after story. Sometimes if there are adds, deletes, and changes inside one story, with Track Changes turned on, it is difficult to read, so showing the before and after stories works better. That is a judgment call by you.
Also, consider that Microsoft Excel also provides Track Changes. You may not be aware of this as it is not in the same place on the menu as in Microsoft Word. Track Changes is useful when you are drafting statements. Once you finish them and want to maintain them in the future, you should consider versioning, which will be discussed at the end of this section.
You need to consider the same process for the radiation dosimetry project where you might have the following :
13-15 DRAFT As a soldier in a nuclear battlefield, I want a way to determine the radiation exposure so that I can see how it is affecting my ability to perform my military mission.
This user story may be as written because that was what someone initially asked for. However, the military leaders determined this not a valid factor to be considered by the individual soldier, so they revised the story as follows:
13-16 DRAFT As a commander in a nuclear battlefield, I want a way to determine the radiation exposure so that I can see how it is affecting my unit’s ability to perform its military mission at the squad, platoon, and company levels.
Then, the medical staff renegotiated it as follows to be within their policy:
13-17 As a commander in a nuclear battlefield, I want a way to determine the radiation exposure in accordance with the Radiation Exposure Medical Policy so that I can see how it is affecting my unit’s ability to perform my military mission, at the squad, platoon, and company levels.
Again, the bold is the text that was added to the previous version of the user story. FYI, the title Radiation Exposure Medical Policy was just fabricated to illustrate what someone may identify.
There is no limit to the number of times that you may renegotiate a user story. You may get it correct the first time. Alternatively, you may refine it just before the sprint, or any number of times in between the first time you crafted it and the developers worked on it in the sprint. There is no right or wrong number of times. The correct number is whatever number of times is necessary to get it correct.
The main point here is to get everyone to understand what the user story means. Once the stakeholders are satisfied with the text (with your help, of course), then the developers will examine it and may ask for some additional information or clarification. If you as the RE cannot provide the information, you will need to take the story back to the stakeholders.
One additional aspect you may want to consider is that you may need to track the changes from the first version to the final version. (This is where a good database tool helps with this.) The reason may be that the original stakeholder who asked for user story 13-15 sees the final user story (13-17) and says that his user story was deleted. With the tracked history, you can point out the evolution of the user story into the final one. If the stakeholder says they want 13-15 added back in, you can point out the decision that turned their version into 13-16 overrode their initial request. Now you see what the negotiation is. This reinforces the point made earlier in this book: requirements definition is an art form, and this negotiation process is a primary reason for it. Note, having a good comments field helps to explain why revisions were made and to clarify decisions that affected the wording of the version.
Another form to track history is in documents that track different versions. Microsoft SharePoint allows you to track different versions of documents. Some dedicated requirements tools provide versioning of requirements in whatever form you capture them (e.g., shall statements, user stories, use cases). There are also dedicated configuration control/management packages that may allow versioning at the element level (e.g., shall statements, user stories, use cases) rather than at the document level. You want the version down to that element level .
Valuable
The user story must provide value to the end user. While this seems obvious, it is not always clear to all parties. Here’s an example:
13-18 As a machine learning user, I want the function to present the mathematical representation to me so that I understand why some entities are chosen over others.
A developer might think a particular function is fun and needed, whereas the real users think it is of no use to them. In fact, how many of the stakeholders would even understand what this would mean? Yet, if the application was a tool for machine learning developers, this may be a valuable tool. On the other hand, if this user story was asked for when there is no such need, it may be a user story you can eliminate.
Bear in mind that not all end users see the value of everything. Here’s an example:
13-19 As a system administrator, I want the ability to add, change, or delete any record in the repository so that I can fix any errors made by other users of the system.
Administrators who know the need to audit database transaction to protect the integrity of the data know its value. On the other hand, a person who just queries the same database might not see the value of auditing for their use, although many if not most people would recognize its value to the technical people. In those instances, you need to ensure that the technical need is captured. Therefore, it is important to consider that value is relative. This is why it is important to have representative stakeholders to ensure all aspects are affected, not just people who query the data or update it, but system monitors, system admins, and people who perform access control, to name a few.
Of course, the resources necessary to achieve the value comes into play in determining if it truly is valuable. For example, everyone could see many and varied needs and uses for the transporter of Star Trek. However, not only is the physics not well understood for it, but also the engineering necessary to achieve it certainly is nowhere near the capabilities of today. Much more importantly, the cost to achieve it is, well, unknown. For all intents and purposes, since you do not know how to accomplish it, effectively the cost is infinite.
As an aside, supposedly, there was a call (allegedly by Congress, in its infinite wisdom) to produce antigravity back in the 1940s and 1950s, in spite of the fact that general relativity said it was not possible. Well, there is no evidence of this antigravity unit to date. Therefore, it is of no value as a user story at this point.
So, you understand the point—when determining the value of a user story, it is important to include the practicality of achieving it, besides determining the desire by the end users. That is also one of the reasons you identify what role finds this function or feature useful and why, so that the user story supports that user. That should help you identify the appropriate user or stakeholder to talk to about this. By saying, “As a system administrators, …” you know this functions supports them, and they would be able to provide the business reason why this function is important.
Note
Do not try to figure these business reasons out by yourself. Whenever you can, get the stakeholder to do that for you. In many cases, you will know the reason why, and you should capture it, if the stakeholders have not provided it. Then, when you vet the user stories with the stakeholders, make certain you ask if the reason is correct. Otherwise, ask during the elicitation process what the reason is.
For the radiation dosimetry project, you might have the following:
13-20 As a tank commander in a nuclear battlefield, I want a way to determine the radiation exposure inside the tank so that I can determine what my team’s exposure is and hence their fighting capability.
Estimable
A story to be of value must be estimable. By that, someone, maybe not who crafts the story, needs to be able to make an estimate of the complexity of the story and thereby determine the time it will take to develop and test it. Odds are, if someone cannot estimate it, then it is too complex and needs to be broken into simpler or smaller stories that can be estimable. You will learn about smaller in the next subsection.
As you get closer to the sprint where specific user stories will be considered for movement from the backlog to be worked in a sprint, the people who will estimate how long a story will take must examine the story to ensure they can estimate it. This is first a sanity check that the story is defined as well as it can be (see the “Negotiable” section earlier in this chapter). If there are any assumptions or clarifications the developers need, this will be the time to help drive those points out. Sometimes the first indication you have that a story is too big is when the developer or tester says that it is too big—that they cannot do it in one sprint. Then, as the RE, it is your job to break it down into multiple parts.
For example, you may have the following:
13-21 DRAFT As someone who searches my permanent records database, I want a concept search capability so that I will not miss important records that are related to what I want the search to find.
When the developers examine this user story, they say it is too large. So they suggest breaking it into the following:
13-22 As some who searches my permanent records database, I want a function that decides what terms are similar to the user-specified search terms so that the user will find search terms that capture the true intent of the search.
13-23 As someone who searches my permanent records database, I want a function that executes the concept term search so that I can retrieve the search terms.
13-24 As someone who searches my permanent records database, I want a function that displays the results of the concept term search so that the user can determine what terms best meet their needs.
It is possible that there are more user stories than this, but this illustrates breaking the stories into lower levels that are more manageable for developers. Also, this is a reflection of something you will learn about in the “Small” section in this chapter about themes, epics, and stories.
For the radiation dosimetry project, you might have the following:
13-25 DRAFT As a commander in a nuclear battlefield, I want a way to determine the radiation dose rate that my vehicles are exposed to so that I can collect raw radiation data for the battlefield.
In this case, what vehicles must have this? So, start with the following:
13-26 As a commander in a nuclear battlefield, I want a way to determine the radiation dose rate that my M-1 tanks are exposed to so that I can collect raw radiation data for the battlefield.
13-27 As a commander in a nuclear battlefield, I want a way to determine the radiation dose rate that my deuce-and-a-half trucks are exposed to so that I can collect raw radiation data for the battlefield.
13-28 As a commander in a nuclear battlefield, I want a way to determine the radiation dose rate that my attack helicopters are exposed to so that I can collect raw radiation data for the battlefield.
There would be a much longer list of vehicles than this, but you understand the idea.
The key point here is that the developers and testers will be doing the estimates, so it is their judgment that determines whether the story meets this attribute.
Small
A story needs to small enough so that it can be developed in hours or days or one or more weeks, depending on the size of your sprints. They should be small enough to be accomplished during just one sprint. As you have now seen, you now know how these attributes can be interrelated. If it is small enough, odds are it is estimable, and there’s a greater chance that the story will have value to the users.
What criteria should you use to determine whether the story is small enough? If the story is vague, it may be because you have too much in it. Remove the vagueness by giving more detail to the story. If the developers and testers cannot estimate the story, chances are that the story is too big. Again, provide more detail and see whether you can break it down. In addition, if there are conjunctions in the story, it may be too large. Here’s an example:
13-29 DRAFT As an FBI records manager, I want to add, change, and delete records from my repository so that I can manipulate the records as necessary.
It would be better to break this user story into three as follows:
13-30 As an FBI records manager, I want to add records from my repository so that I can manipulate the records as nec essary.
13-31 As an FBI records manager, I want to change records from my repository so that I can manipulate the records as necessary.
13-32 As an FBI records manager, I want to delete records from my repository so that I can manipulate the records as necessary.
There is a general “stories” hierarchy in which one level is called stories. This hierarchy is called TES, which comes from theme, epics, and stories. The theme is the largest of the three, which is a collection of epics or many stories. It usually relates to a major function within a system. Here’s an example:
13-33 The system will provide controlled access to the BOSS.
Clearly this does not follow the full user story format, and it is way too big to estimate and could not be done in one sprint/iteration.
The next level down is the epic, which is one large user story that needs to be broken down or already a group of related user stories. In the access function mentioned in the previous theme, consider the following:
13-34 As a BOSS system administrator, I want to add to person to the BOSS system so that I control who gets authorization to use the system.
13-35 As a BOSS system administrator, I want to define all BOSS system roles and responsibilities so that I control what functions specific groups of people can perform.
Roles and responsibilities refer to the different accesses a user could have such as a user who reads data, adds data, updates data, deletes data, or any combination of these roles. Of course, there may be more specialized roles like an administrator who also needs access.
13-36 As a BOSS system administrator, I want to assign BOSS system roles and responsibilities to a person so that I control what functions specific groups of people can perform.
13-37 As a BOSS system user, I want to log in to the BOSS system so that I am allowed to access the BOSS functions I need to perform my job.
13-38 As a BOSS system administrator, I want to audit all access so that I know who has performed all access adds, changes, and deletes. (This could be an admin, a manager, an auditor, and so on, depending on your project.)
Epics are useful early in the definition phase when you may not have a lot of information about the needs of the system. This allows you more time to focus on the high priorities on the backlog.
Finally, back to the user story level that was being developed, here is one example for the login epic:
13-39 As a BOSS system administrator, I want the login to the BOSS system to require a user ID and password so that unauthorized users cannot easily break into the system.
13-40 As a BOSS system administrator, I want no more than three login tries of password and user ID combination errors before the user ID is locked out of BOSS so that unauthorized users cannot easily break into the system.
How does the user ID get unlocked? Excellent question. The answer is that it depends. It could be one of the three following user stories (or some variation of it) based on what your management and senior stakeholders want:
13-41 As a BOSS system administrator, I want the lockout of a user ID to be unlocked after 30 minutes so that the user can try again without requiring the sys admin to unlock it.
Note
User story 13-41 may make it easier for hackers, just FYI.
13-42 As a BOSS system administrator, I want the lockout of a user ID to be unlocked after 24 hours so that the user can try again without requiring the sys admin to unlock it .
13-43 As a BOSS system administrator, I want the system admin to unlock the lockout of a user ID so that I control who can access the system.
Consider either one of the first two, but always allow the third user story to be available also, especially if the user must wait 24 hours for it to reset; you might not want people waiting a day to retry, without being able to do their job.
Notice there is a relationship between the estimate and small attributes. If a user story is small enough, chances are good developers can estimate the time necessary to implement the story.
Now, examine the radiation dosimetry example from the “Estimable” section in this chapter:
13-44 DRAFT As a commander in a nuclear battlefield, I want a way to determine the radiation dose rate that my MRAPs are exposed to so that I can collect raw radiation data for the battlefield.
On further examination, a stakeholder states that all vehicles must use the same dose rate meter. That means you have to break user story 13-44 into the following:
13-45 As a commander in a nuclear battlefield, I want my MRAPs to use the standard dose rate meter so that I do not need to develop a meter unique to every vehicle.
13-46 As a commander in a nuclear battlefield, I want the standard dose rate meter to have an MRAP-specific mounting bracket so that I do not need to have a universal mounting bracket for every vehicle.
13-47 As a commander in a nuclear battlefield, I want the standard dose rate meter mounted on the outside of the MRAP so that it collects the raw data not influenced by the shielding offered by the MRAP.
It is ironic that this subsection called “Small” is the longest of the six sections on the attributes of a good user story. This is in no small way (pun fully intended) because of the difficulty in getting the user story to the correct level. You will need to work at it.
Testable
Lastly, the story must be verifiable (as you learned with requirements) but is called testable to allow the acronym INVEST to work (INVESV does not seem to cut it). A story is not completed until is it is successfully tested. If it does not pass testing, it is not complete. Thus, in the estimate process, people need not only to include time to code and test the code but also include time to rework errors and then retest. Just as one attribute of a good requirement is that it can be verified, the same is true for all user stories. Some demonstrations of a user story show that values in XML have changed, rather than showing changes in a user interface. The purpose is to demonstrate the user story works, not have a UI for every story.
On some projects, to ensure that the application worked properly, the entire last sprint in a release was dedicated to regression testing. The teams wanted to ensure that no story adversely affected anything in this application (i.e., the ripple effect) that supported hundreds of thousands of users. While most projects do not follow this approach, the number of issues caused once this application was deployed was very, very small. That is the ultimate goal.
Some reasons for untestable stories are the wording. Here’s an example:
13-48 DRAFT As a user, I want an easy-to-use user interface so that I do not have difficulty learning and using the system.
This makes sense to a user or stakeholder, but how would you test or verify “easy”? Any such vague words need to be modified as follows (just as you learned when crafting shall statements):
13-49 As a user, I want the user interface to follow the BOSS User Interface Standard so that I do not have difficulty learning and using the system.
This is something that is testable or verifiable. Granted, if the UI standard is more than a few statements, this user story may not be small enough, but at least from a test standpoint you are moving in the correct direction.
Thus, just like with shall statements, you need to eliminate the vague words. That may be an issue when dealing with the users and stakeholders, but just as you were trained for those shall statements, you will be able to do it here.
Look at examples for the radiation project.
13-50 As a commander in a nuclear battlefield, I want the standard dose rate meter to be installed on the MRAP within 15 minutes by a soldier who requires no special training or tools so that the dose rate meter can be installed quickly and easily by any soldier.
13-51 As a commander in a nuclear battlefield, I want the MRAP-specific mounting bracket for the standard dose rate meter to be installed within one by the lowest ordinance unit that requires no special training or tools so that MRAP-specific mounting bracket can be installed quickly and easily by any soldier.
One other important aspect associated with testing is acceptance criteria. Given its importance to support the testable attribute, you will spend the next section learning about it.
Acceptance Criteria
Acceptance criteria , also known as completion criteria , is to help define when a user story is done (or complete—hence, you say the story is complete). At the end of the sprint, the demonstration is to show that the criteria are complete.
What makes good acceptance criteria? Walter Jackson said the following in his online article “What Characteristics Make Good Agile Acceptance Criteria?”:
There should be a clear pass/fail result (no partial results).
They can be both functional and nonfunctional requirements.
They can define boundaries of a user story.
They can define parameters of a user story.
They must be clear and without ambiguity.
They should be implementation independent.
Do you notice how many of these criteria are the same as those related to shall requirements as you have seen in this book? That is in part that many of existing requirements can help to define acceptance criteria. In addition, data elements were not talked about before with respect to user stories. That is because the theory states you should not provide them in the story. So, where else should you place them but in the acceptance criteria?
Now, look at some examples. For instance, here is user story 13-27 with acceptance criteria added:
13-52 (13-27) As a BOSS system administrator, I want the login to the BOSS system to require a user ID and password so that unauthorized users cannot easily break into the system.
Acceptance criteria:
The user ID will be unique within the system with a minimum of six alphanumeric characters.
The password will be a minimum of eight alphanumeric characters, with a mix of uppercase and lowercase characters, one or more numeric characters, and one special character from !@#$%^&*().
Now reconsider user story 13-40 with acceptance criteria:
13-53 (13-40) As a BOSS system administrator, I want no more than three login tries with password and user ID combination errors before the user ID is locked out of BOSS so that unauthorized users cannot easily break into the system.
Acceptance criteria:
The error can be an incorrect user ID but a correct password.
The error can be a correct user ID but an incorrect password.
The error can be an incorrect user ID and an incorrect password.
Now you should also reconsider 13-39:
13-54 (13-39) As a BOSS HR administrator, I want to be able to add a new employee to the HR system so that we track all of our active employees.
Acceptance criteria:
I want a User record to contain: a. Name, b. Work e-mail address, c. Work phone number d. Home mailing address, e. Home e-mail address, f. Home phone number, g. Cell phone number.
Keep in mind that acceptance criteria are useful as a foundation for the testers to craft their tests for a user story. Do realize that acceptance criteria are not required for a user story. Provide them when they help. This may seem counterintuitive. If you want to know when the user story is complete, then you need acceptance criteria. As an exercise, go back and look at all the user stories from the beginning of this chapter. Is there anywhere you do not feel acceptance criteria are needed? Is it only one or two? A dozen? More than half? Most of them? Chances are more than half do not need them. With experience, you will learn. During the discussion with the stakeholders, there statements associated with a user story will help to indicate if completion criteria are need.
Consider the following for the radiation dosimetry project:
13-55 As a commander in a nuclear battlefield, I want the standard dose rate meter to display the exposure rate by the soldier activating the meter so that soldier can capture the reading at the location allowing a radiation overlay to the map.
Acceptance criteria:
I want radiation exposure, date, time, and location information.
I want the ability to refine the scale, such that the detail can be tenths of Rads, single-digit Rads, tens of Rads, hundreds of Rads.
Note
You have to be careful. Acceptance criteria #2 assumes a certain implementation. In this case, it assumes an analog display, whereas the development may be digital, allowing all the data to be display on one screen. The criteria in question were provided just to illustrate the types of information you might capture in an acceptance criteria.
From Anantha Narayanan’s online article “User Story Acceptance Criteria : The Art of Satisficing and Bounded Rationality,” we can consider certain aspects of acceptance criteria. First, acceptance criteria do not need to be an exhaustive list, just something that keeps communications moving forward. Just like the user story, the acceptance criteria can change with time. They can even be refined during the sprint .
Size of stories
Just as the concept of user stories came from XP, XP introduced the concept of what they call a spike.
Note
Not everyone even uses this term. I was introduced to it while researching this book even though I had used it. We just called the first user story the research user story and the second story the implementation user story. The titles are different, but the concepts are the same.
There are some instances where the definition of the user story is insufficient—not that the story is wrong or not small enough, just that the developers do not have sufficient understanding to correctly estimate what it will take to fully implement it.
Experience shows that the first user story can be done in one sprint and then the second in a later sprint. It was not always immediately after the first sprint, as the team may need specific tools that they did not have and needed to acquire them, which took additional time.
It could be the team does not understand all the technical challenges associated with a story, so they need to do some research or maybe some exploration. They may need to prototype multiple options and see which the stakeholders like at the demo at the end of the sprint. Believe it or not, this type of refinement goes a long way in keeping the stakeholders invested in the system by them helping with such decision making. What if it is to see whether a new technology brings benefit? It could be a particular programming technique or an automated test tool. Determinations of this type usually occur when the development team, including the testers, examines the user stories. They will determine whether a particular user story is a spike.
Assume they get to the following user story:
13-56 As a soldier on the nuclear battlefield, I need a device to capture gamma ray exposure between 200KeV and 1.00 MeV radiation exposures so that I know what I have been exposed to.
In this case, the developers do not know the precision of four candidate detection mechanism, so they want to test what they get.
Therefore, they might craft a new user story to test the exposure collection spectrum of each against their known radiation source. Once they complete it, they will determine which one meets their needs and then write an implementation user story against the decided device.
The two stories could look like this:
13-57 As the radiation dosimeter developer, I will test Devices A, B, C, and D against gamma ray exposure between 200KeV and 1.00 MeV energies against our simulated tactical nuclear radiation device so that I can determine the accuracy of each device. (Reference user story 13-56.)
13-58 As the radiation dosimeter developer, I will integrate the chosen device (from story 13-57) into the BOSS Unit Radiation Dosimeter device so that I implement the optimum collection device. (Reference user story 13-56.)
It is always useful to reference to the original user story and the two spike users stories to keep traceability.
You could have the following for the FBI Records Management project :
13-59 As an FBI records manager, I want the BOSS Records Management System to suggest record categories consistent with the NARA General Records Schedule so that I can save time by accepting good suggestions.
When the developers first examine this user story, they need time to investigate the best approach . They may suggest the following two stories:
13-60 As an FBI records manager developer, I want to examine the three candidate machine learning approaches to suggest record categories consistent with the NARA General Records Schedule of the BOSS Records Management System so that I can choose the best approach. (Reference user story 13-59.)
13-61 As the FBI records manager developer, I will implement the chosen approach (from story 13-60) into the BOSS Records Management System so that I implement the optimum machine learning approach to suggest record categories consistent with the NARA General Records Schedule. (Reference user story 13-59.)
Another reason to consider a spike is that the story may be too big to be estimated appropriately. The developers may use the spike to analyze the behavior in order to split the story into estimable pieces.
In addition, this spike approach should be used sparingly. If it seems to be happening a lot, it would indicate other potential problems, like under-trained developers, the user stories are not well-defined, or stakeholders are not providing good insights into their needs. Monitor it, and if they happen 1 or 2 percent of the time, you are OK, but if it is 10 or more percent, you are in the problem area.
Complement vs. Supplement to Requirements
In this and the next section, you are going to learn about whether you need to write shall statement requirements with user stories or not. This section will talk about how shall statements can complement user stories, so in this section, the answer is yes to shall statement with user stories.
Complement to Requirements
Actually, this discussion of whether or not to capture shall statements reverberates in the industry. The position here is that generally shall statements provide added value when used in concert with user stories. The “Acceptance Criteria” section talked about using requirements as candidate acceptance criteria. Obviously, that is one candidate area to exploit requirements within a project.
Real-World Note
Go back to the discussion about my troubled requirements collection for that one project where we collected user stories with the stakeholders instead. You may not remember it as it was way back in Chapter 1, so here it is again:
On a recent project, I had begun capturing the requirements the traditional way. In six to eight months, I had managed to capture the requirements for only the search function of the system. We had about a dozen major functional areas like this. The program manager was extremely frustrated by the lack of cooperation from the stakeholders, which was epitomized when she said, “It’s going to take us five years at this rate!” Thus, a new approach was needed.
That new approach taken was to capture user stories, and it worked well. It took a year and a half to capture all the user stories for this large and complex system. Did the project use or write requirements? Of course. The project needed those detailed requirements to pass to the designers, developers, and testers. They did not need to be vetted with the stakeholders. Well, that was not entirely true; the project had special stakeholders involved like DBAs, system admins, and even developers and testers to ensure they were represented well, and the project allowed everyone to comment on and improve the shall statements.
You have heard all the reasons for writing the acceptance criteria. They are valid. The requirements that are allocated to a story are the respective acceptance criteria for the user story. No doubt this position on user stories will spawn discussion or even argument on the Web. Remember, purists are doing it to substantiate their theories. The reality of it is—if it works, do it.
Note
For the successful agile developments I have worked, we did use both user stories and shall statement, and not always because of me. As for theory versus reality, see my discussion on availability calculations in the “What Can Go Wrong with Writing User Stories?” section of this chapter.
Replacement for Requirements
The previous section said shall statements complement user stories. This section will talk about how user stories replace shall statements. There are experts who advocate that well-crafted user stories do not require shall statements because if the stories are captured correctly, you do not need to capture shall statements.
I have given my preference in the previous section. It is my philosophy that more detail is better. Given the level of detail provided by user stories, they give a significant amount of detail. One big improvement of user stories, as stated earlier in this chapter, is that user stories explain why the need is important, which shall statements do not. If acceptance criteria are provided with the user story, much of the lower level of detail a shall statement would provide can be addressed by these criteria. Thus, user stories can and do replace shall statements.
That said, I have worked with user stories without shall statements because if the stories are captured correctly, you do not need to capture shall as well.
On one of the smaller systems, a development team of only three people, the team did not use shall statements. In this particular case, I was not actually responsible for crafting user stories, but I just provided oversight and suggestions, as another branch was responsible for the user stories. The approach worked because the development team knew the system very well and did all the testing, and adding shall statements would not have provided a significant value-added. More importantly, the system was not nearly as complex as most other applications that it interacted with. Therefore, a point to consider is the size of the development team, their knowledge base of the system, and the size and complexity of the system.
Which way you go for your organization is your call—unless your organization has made the call for you. That said, if there are issues with the requirements process, you might want to consider a change that would improve it.
In the case that user stories have been used in place of requirements, you need to provide more detail in the acceptance criteria, which you know from the previous section that this is essentially shall statement requirements, even if they do not have the word shall in them.
User Stories Traceability
In situations where you have shall statements with user stories, there is one important function you should always do. After you have all the user stories and requirements done, map every requirement to a user story. Sometimes it may be two or more user stories to a requirement. Purists might insist that it should be one user story to one or more requirements. While that is an admirable goal, it is not an absolute. Otherwise, for some unique situation, you might not be able to make it work.
For example, you have the following requirement :
13-1(RQMT) The system shall allow a locked user ID to be unlocked.
Looking back to the previous user stories, here’s another example:
13-62 (13-41) As a BOSS system administrator, I want the lockout of a user ID to be unlocked after 30 minutes so that the user can try again without requiring sys admin to unlock it.
Note
Requirement 13-62 (13-41) may make it easier for hackers, just FYI.
13-63 (13-42) As a BOSS system administrator, I want the lockout of a user ID to be unlocked after 24 hours so that the user can try again without requiring the sys admin to unlock it.
13-64 (13-43) As a BOSS system administrator, I want the system admin to unlock the lockout of a user ID so that I control who can access the system.
You should trace the requirement to all three user stories.
Experience shows that you should not be constrained to map one requirement to only one user story. It is a goal, but not a hard-and-fast rule based on experience. Just make certain the requirements are atomic as was taught to you in Chapter 2; then you will probably not go wrong.
For the radiation dosimeter project , you have the following requirement:
13-2(RQMT) The BOSS radiation system shall be painted with standard U.S. Army camouflage paint to match the soldier’s uniform.
You might have the following user stories:
13-65 As a soldier operating in the desert, I need a radiation dosimeter that will blend with the desert environment so that the dosimeter does not stand out and give away my position.
13-66 As a soldier operating in the woodlands, I need a radiation dosimeter that will blend with the woodlands environment so that the dosimeter does not stand out and give away my position.
13-67 As a soldier operating in the arctic, I need a radiation dosimeter that will blend with the arctic environment so that the dosimeter does not stand out and give away my position.
At first blush, as in the previous “locked user ID” example, you might think you could just map requirement 13-2 to user stories 13-65, 13-66, and 13-67. However, that is incorrect. Requirement 13-2 clearly is not atomic. It should be rewritten as follows:
13-3(RQMT) The BOSS radiation system shall be painted with standard U.S. Army desert camouflage paint to match the soldier’s uniform.
13-4(RQMT) The BOSS radiation system shall be painted with standard U.S. Army woodlands camouflage paint to match the soldier’s uniform.
13-5(RQMT) The BOSS radiation system shall be painted with standard U.S. Army arctic camouflage paint to match the soldier’s uniform.
You have used the user stories as a sanity check for the correctness of the requirements. This is something you need to examine during your mapping between requirements and user stories.
Once you have mapped everything, you might find some requirements that do not have user stories. Sometimes these processes do not fit within user stories. This is getting to some of the limitations of user stories. How do you write a user story for reliability for a system or query performance? This gets harder. However, more on that shortly. Then look for all the user stories that do not have any requirements associated with them. That means you are missing some requirements. Write them.
What you are doing is the gap analysis for both the user stories and the requirements. This is an excellent time to check your user stories and requirements against the checklist of functional and nonfunctional requirements to ensure that you cover everything, even if the users and stakeholders do not think of it.
Real-World Note
A good way to compare and contrast user stories and requirements is to perform the following steps. First, I load all the user stories into Microsoft Word or Microsoft Excel. Second, I load all requirements in a spreadsheet. Third, I map all requirements to user stories. Fourth, I map all user stories to requirements. Finally, I look for that cells in the table that are empty, and these are the areas where there are gaps. New requirements and new user stories are required.
Even if you do user stories first and then the requirements, you should still do this step as a quality check on your work. You may be surprised how much you still missed. First, you need to find out whether there are requirements that have no user stories. If so, write the appropriate user stories. Of course, if there are user stories that have no requirements, add the requirements. This is a good check and balance.
There is one other source to help with gap analysis . You can use the Business Process Description to craft the user stories. This is usually an excellent way to do it. It also provides sources that you may have forgotten in the user stories and/or requirements. All the information is in one spot, and it is relatively easy to do them. Granted, for a large system, it could be hundreds of user stories. Even for smaller systems, several dozen user stories are needed to cover a small application to include the hardware on which it will reside. Do not ever forget that.
Maintain User Stories
One other aspect regarding the previous system was the work initially was in the operations and maintenance phase . Some new development was added, but that is not the point here. This is an important facet of this phase that you need to be aware of. When maintaining an existing system, user requests will come in that are specific to the user interface. For example, you might get something like the following:
13-68 As an FBI BOSS Audit Screen, I want the person who performed the action listed on one line and what action they took displayed on the line below so that I see the information without having to scan around the screen.
Immediately, your “implementation-specific” alarms should be going off (if you have learned well). You are not supposed do this kind of user story, just like you are not supposed to do implementation in shall statements. Some renegotiation is needed for user story 13-68 to get it closer to what the users want and the developers and testers need.
Here’s another example that you may see:
13-69 As a Form Requester user, I need the form selection tab to include a list of the HR forms in one column, the Payroll forms in the second column, and the Procurement forms in a third column so that I can find the forms more quickly.
If you follow the INVEST approach, this story might need to be rewritten. However, would you want to? The user is asking for a specific change to the user interface that needs to be improved. These are not bad stories, as the users need improvements to the existing implementation. This is not the same situation when there is no design, where you do not want to constrain the designers. Here, the user is asking for a specific change. Rather than set up an entirely different process, go ahead and keep the paradigm of user stories if that suits your projects.
Another request may come in for the radiation dosimeter project where someone says the following:
13-70 As a soldier operating in the multiple areas of the world, I need the ability to repaint the radiation dosimeter from either desert, arctic, or woodland camouflage color to one of the other environments so that I do not need three or more different dosimeters.
Clearly this is a valid need, and it is implementation specific. Should you leave this one this way? Possibly not. What if the developers can create a technique for automatically changing the color without repainting it? Maybe it is like the original Kindle that had a black side and a white side to each minute ball that created each pixel, where they have three (or more) “faces” for the pixels on the outside of the dosimeter. Therefore, you might want to change it to read as follows:
13-71 As a soldier operating in the multiple areas of the world, I need a the ability to change the radiation dosimeter from either desert, arctic, or woodland camouflage color to one of the other environments so that I do not need three or more different dosimeters.
Notice that only one word changed from user story 13-70 to user story 13-71. Yes, sometimes it is as simple as modifying only one word. Clearly, user story 13-71 is better than 13-70, as you have learned.
In addition, you are going to find many, if not most, maintenance-type user stories might be written like user stories 13-68 and 13-69.
This is not a bad thing.
Why? The major reason is that when you capture user stories for a development effort, you are supposed to give the developers free reign since there is no existing system that they are basing the effort on (even if there is a legacy system, that does not have bearing). Therefore, people will want tweaks and adjustments to the current implementation. Unlike shall statements where there is the potential of design specifications created by the developers, user stories do not necessarily have the equivalent. Thus, user stories are the only venue for communicating this information. Therefore, during O&M, it is acceptable to create implementation user stories. Again, certain theorists may argue this point. Remember the philosophy—if it works, do it.
What Can Go Wrong with Writing User Stories?
Remember how Chapter 1 talked about how agile and waterfall compared ? Here it is again to refresh your memory.
Agile | 42% successful, 49% challenged, 9% failure |
Waterfall | 14% successful, 57% challenged, 29% failure |
As before, this is a significant improvement over the waterfall approach. Again, one of the significant factors is that the work is subdivided down to a very manageable level.
That said, agile had a 9 percent failure rate. Is the agile methodology responsible for that? Experience shows that the answer is no because there are so many other factors that were talked that could cause any approach to fail such as bad management, lack of resources, too short of schedule, and so on. Ideally, what you have learned has mitigated the requirements/user story definition phase issues.
Does this mean that user stories are the pinnacle of requirements technology? While they go a long way to fix requirements problems, they still have some limitations. Because each user story is intended to be accomplished in an individual sprint, some areas that you need to define do not fit well. Nonfunctional requirements, especially performance, are much harder to capture as a user story. Remember, the “Administrative Functions” section in Chapter 5 stated the following requirement:
5-54 (RQMT) The BOSS system shall be available 99.99% of the time.
How would it look as a user story?
13-72 As a BOSS user, I want the system to be available 99.9% of the time so that the system provides the availability I need since it is a mission-critical function.
That sounds like a reasonable user story, and on the surface, it is. However, can that be accomplished in one sprint? Assume the development team has six user stories it is responsible for developing in a given sprint. Does this apply to each user story? Technically, yes. So, how does the tester verify that it is accomplished? What about all the work that has been accomplished before the sprint in question? Does the availability user story apply to them? Yes. Now you start to see the conundrum.
Clearly, that user story is not something that can be done in one sprint. In fact, every service in the system, and even every functional area, must contribute to that. How do you overcome this?
For this example, assume you have ten functions within BOSS for this example. Then, write a user story for each function like the following:
13-73 As a BOSS user, I need the BOSS Function1 availability to be 99.99% so that I can perform my work on that function.
Notice, the focus has been on the function level, where a given function can be worked at the sprint level. Also, notice that the availability changed from 99.9% for the system to 99.99% to accommodate that you have ten pieces.
In this example, the original BOSS availability is a theme rather than an individual user story, and the ten functional availabilities are the user stories you will allocate to sprints.
Then there is the issue of how to verify this user story. That is something you should always consider when writing a user story. It can be done, albeit it is a challenge. Defining “how” is for the testers to accomplish, and that is why they get paid the big bucks. At least you should be able to conceive of a reasonable test. If you can, you have done your due diligence. The key word was “reasonable.” If the verification required places a device on the dark side of the moon, that probably is not reasonable.
The Rally Help web page article titled “Write a Great User Story” talks about the top mistakes that people make. The potential areas are as follows:
Too formal or too much detail: Stakeholders and users may write extremely detailed user stories. One fix to this is to include that information in the acceptance criteria. That way the good information is not lost, but it does not complicate the user story. Otherwise, if developers and testers see a very detailed story during the sprint planning, they might see all the details are present and may skip the detailed conversation. Communication is the central point of the user story, so do not do anything that will limit or restrict it.
Technical tasks masquerading as stories: The success of agile largely comes from having a working piece of software at the end of a sprint. If some stories are just technical tasks, you may not end up with working code at the end of the sprint. This may be fixed by making it a spike as was talked about in the “Size of Stories” section in this chapter.
Skipping the conversation: Stories may be vague before iteration planning. If you skip the acceptance criteria conversation, you can move in the wrong direction, miss boundary cases, overlook customer needs, and. most importantly, miss important communications—the hallmark of the agile process.
Summary
User stories with acceptance criteria are some of the best techniques you have as a requirements engineer. Take advantage of them. You have seen advantages, of which there are many, and disadvantages, which usually you can overcome. The point is to decide what approach you will use and stick with it. User stories are a sound approach to use. Decide whether you will include shall statements, but do what is necessary to capture the stakeholders’ needs.
References
Wake, Bill. “Invest in Good Stories and Smart Tasks.” August 17, 2003. xp123 Exploring Extreme Programming. Feb. 2015, http://xp123.com/articles/invest-in-good-stories-and-smart-tasks/
“What Characteristics Make Good Agile Acceptance Criteria?” March 25, 2013. Segue Technologies Inc. www.seguetech.com/blog/2013/03/25/characteristics-good-agile-acceptance-criteria
Narayanan, Anantha. “User Story Acceptance Criteria: The Art of Satisficing and Bounded Rationality,” 20 January 2012, Scrum Alliance. Feb. 2015, https://www.scrumalliance.org/community/articles/2012/january/user-story-acceptance-criteria-the-art-of-satisfic
Roth, Ronica. “Write a Great User Story.” Rally Help. Feb. 2015, https://help.rallydev.com/writing-great-user-story
Exercises
Exercise 1
Look at this user story from the beginning of the chapter:
13-1 As a taxpayer submitting my taxes, I want the form instructions written to a fifth-grade reading level so that 99% of the taxpayers will understand what they are filling out on the form.
Does this user story meet the criteria discussed in this chapter? Why or why not?
Exercise 2
Write a user story (or stories) where the user needs to enter a user ID, password, and domain name. A domain name means that there is more than one particular location that a person could access the system. It is not important what these are, just that a person needs to enter a valid one. Include any appropriate acceptance criteria.
Exercise 3
In the individual dosimeter project you have been examining throughout this book, please identify user stories for this project. Rather than use an interview with stakeholders, use the requirements you have collected during the course of this book. (Yes, this isn’t the ideal way to do it. The world is not always ideal, so this helps train you to use whatever you may have on hand.) Then, map all those requirements to the user stories. Have you found any gaps? Are they gaps in the user stories or requirements?
Exercise 4
Write user stories for your cell phone—not all the apps, just the basic needs of the phone portion.
Exercise 5
Will ten functions with an availability of 99.99 percent combine to be 99.9 percent for the entire system? Why or why not?
Exercise 6
Write some user stories to describe what the Radiation Dose Rate Mapping Laptop should do based on the description of this segment of the system described in the “Radiation Dosimetry Project” section in Chapter 1.