Translating Use Cases into Product Requirements

We're going to be talking again about translating use cases into product level requirements. So let's go ahead and get started. I like to start by talking about the different types and levels of requirements. We'll actually come back to this slide and add more to it as we go through the talk. But at the highest level of requirements, you have those business requirements typically documented in a charter statement of work, some high level document that defines the goals and objectives for your project. I use pay at the gas pump type software as my ongoing example. We've all been there, done that. Most people are acquainted with paying at the pump. So business level requirement, there might be something along the lines of the customer can pay for their gas out at the pump without having to come in and interact with the attendant. Now it's very high level, very broad in agile. You'd probably call that a mega epic, but it's a high level business requirement. But that has to get drilled down to what does the stakeholder need to do in order to implement that business requirement. And this depends on the stakeholder. For example, if you looked at that customer, the person purchasing gas as the stakeholder, they're going to need to be able to scan their credit card, they're going to be able to need to enter their pin, they're going to be able to select the type of gas they need. All of those would be requirements down at the stakeholder level for that stakeholder. Many times those are captured in user stories. This stakeholder can do this. For this reason, we in this class are actually going to talk about using the concepts of a use case case to further drill down those stakeholder requirements. If you look at a different stakeholder, the owner of the gas station, they want to ensure they get paid. So they need to make sure the credit cards are validated with the bank before they allow any gas to be pumped. Their requirement might also to be able to run a set of nightly reports to get information about all the gas that was sold that particular day. The attendant, again a different stakeholder is going to, if the people do come in and pay, need to be able to go pull the pumps to find out how much gas they purchased, what the price of that gas was without them having to go outside and actually read on the pump. They may also need certain alarms if something goes wrong out at the pump. For example, it's run out of receipt paper. So those will be the stakeholder level requirements. And as I said, we're going to talk here about documenting those in use cases because then we're going to talk about translating those use cases down into product level requirements. The basic concept of a use case. The first thing you have to do is define the scope of the system and identify who your actors are. Now the actors are those stakeholders or any other external entity that interacts with each other. Your software system that might include other hardware devices, other pieces of software, for example, the bank consortium that's going to validate the credit cards is probably another piece of software that you are talking to and not specifically a stakeholder because stakeholders are always people or groups of people. So you're going to be identifying those stakeholders. So to just look at the pay at the gas pump system, again, some examples of stakeholders might be those customers who are coming in. Examples of actors, I'm sorry, are the customers coming in and buying gas from the system, the owner and the attendant like we talked about, who are stakeholder type actors. You may have other actors like that credit card clearing house that's validating the credit cards. You have to define what your system is under consideration. If we looked outside and looked at a larger system like the entire gas station, the owner and the attendant would not be actors because they're inside the gas station. So you define the boundaries of your system. Then the third step in defining use cases is to determine the interactions that those actors are going to have with the system. The main functions or tasks they're going to perform. These are start to finish interactions, information they're going to acquire, produce or change, information they want to give to or or want to receive from the system, notifications, those kinds of things. So in a basic use case diagram, the primary actors are going to be designated as arrows coming in. Primary actors are the people that initiate the use case or that the use case is initiated for. For example, the customer might do a start to finish interaction to purchase gas by postpaying the attendant. Now in some states you don't do post pay. Here in Texas we allow people to pump their gas first and then come in inside and pay for it. Or you might purchase gas by pumping out at the pump and buying it with a credit card. Or you might even purchase a car wash to go along with purchasing your gasoline. The owner might start the monthly reports, or if they come out automatically on the last day of the month, the owner is still the primary actor because they're the target actor that the reports are being done for. Even if the system initiates the action, the attendant inside might actually be accepting post payment for the gas. Those kinds of things. The secondary actors designated by Arrows coming out of the use case are other actors that are involved. For example, when the attendant initiates the use case to accept payment for the gas doing a post pay, the customer is going to be interacting as well. Of course the attendant initiates it because they're the first person that interacts with the system by entering the pump number into the system. But the customer might also provide the payment, might be swiping their credit card. They're also interacting with the system as well as that credit card clearinghouse. So that just gives you a little bit of an introduction to use case diagrams. The last step then in identifying use cases is to develop the actual use case for each of those interactions and to potentially merge them if there's a bunch of little ones that could be considered together or to even break them apart. For example, the basic steps of selecting your gas, pumping your gas would be the same whether you're paying out at the pump with a credit card or you're doing a post pay the attendant. So you might break those out in a sub use case that's called by the other use cases. And just as an example, here is the purchase gas by postpaying the attendant and the customer is going to start by selecting to postpaid the attendant. The system's going to prompt to select the gas type, the customer is going to select the gas type, and so on. I'm not going to read every step to you. Now this is the two column approach and I particularly like the two column approach to doing use cases because it's already telling you what are the inputs coming into your system, the actor actions that are interacting with your system versus what your system has to do as a result of that, which starts focusing in on the functional level requirements. Now the single column approach would just mush this together in a single column step one, step two, step three, step four, and not break it apart. Of course there's a saying in use cases, read any one book on them, you'll understand them completely. They're simple and easy. Read any two books, you'll be totally confused because everybody does them differently. So this is my basic approach. Then also as part of the use case, you are going to define the exceptions and alternatives, the main body of the use case. What we're showing you here on this slide is the steps to get you from the preconditions, what has to be true before you start the use case, to the postconditions, which defines a successful use case. In this case, postconditions would be that I was able to pump the gas it was able to validate my credit card and use it. I got my receipt if I wanted it. Those kinds of things. Alternatives are other ways of getting you to the success. For example, I could cancel at any point in time. Again, I did that because I wanted to do that. So those might be alternatives. Or I might select a different type of gas or. Or I might say yes, I want a receipt or no, I don't want a receipt. Alternatives always branch off the main use case and may either return to the main use case or simply terminate like these do by notifying the attendant of the cancellation, sending the cancellation message to the customer and returning the pump back to idle to start a whole brand new use case. Alternatives, I'm sorry, exceptions and I don't get you to the postconditions. The success, for example, I picked some other key other than the gas type or cancel and it gave me an invalid prompt and couldn't go forward. Returns back and asks me to enter more things. Or it indicated there wasn't enough gas of the type I wanted to pump. Again, not success, because I didn't get to do what I wanted to do. And the main focus of this is once you have these use cases, how do you drill them on down to your product level requirements? Now, if I told you, for example, the stakeholder requirement of the customer needs to be able to scan their credit card. If I sent that down to a programmer, a developer to go implement, they probably would have no idea what to go do. The functional requirements this is where the business analyst, requirements analyst is translating what the stakeholders need down into the specific requirements that are low enough level that the developer knows what to go do. For example, with the scan the credit card, you're going to have to tell the developer what data stream they're getting from the hardware card reader, how to parse that into information to validate the credit card with the bank, what data goes to the bank, what codes come back from the bank, what format all of that needs to be in. So those are the functional level requirements. What does the product have to do at a level that the developers can use that information to design and implement the actual system? So we're going to take these steps in our use case and with a single step or a pair of steps, typically we're going to drill those down to one or more functional level requirements for each step or each pair of steps. Just to pick an example, let's take that first pair of steps the customer selects to post pay the attendant for the gas and the system prompts the customer to select the GAS type. If we take those two steps, we want a functional requirement to adjust this. But it's a good starting point when something happens. I see many requirements that say go do this, but it doesn't tell you under what conditions or when. So the developers are confused. They don't know how this all fits together. So I always put a when. When this particular event or condition happens, this could be an input. This could be it turning to midnight. This could be some other condition that is recognized by the hardware. The subject or noun. Now this may be a particular component of the software or the whole software. Many times I just say the system might say the display shall or the keyboard shall or whatever and then do what? Because again, these are functional requirements. What does the system have to do? Inputs at this specific time. For example, again, for prompting for gas, I might write a requirement 110 here when of the use case pair then. So I'm being very specific about exactly what the software has telling them how to do it, just what to do. Good requirements define what, not how. Notice I say a select GAS type prompt. I don't give the actual words. Now if you need it to say something exactly, you know, pick one of, you know, push the button to select one of the three GAS types. Then that's going to be a design constraint type requirement as well as a functional requirement because it's telling you how to do it, not just the what. So there's my basic template for functional requirements in a single the system monitors the gas flow. Turn that hardware once every tenth of a second to determine the cumulative amount of gas pumped on that pump. Now notice I'm actually turning this into a variable name. The reason I Now this may not be the actual variable name that I use inside the code, but it's a name of a specific piece of data. The reason I have consistency of language in my product level requirements. Once I have something like this named, I would typically put it in a data dictionary with a definition. That way every time I want to talk about the amount of gas pumped, I'm going to use that same term, that same variable name or data item name in my requirement. That way I don't have it called the pumped gas amount someplace else and the gas pumped total someplace else, which gets totally confusing to the poor developers because they don't know whether that means the same thing or something different. So I tend to italicize them, turn them into something that becomes a label that is used over and over again. So that I'm using consistent language in my requirements. So that's just a second example of using a pair. Now, notice it doesn't have to be a pair that talks about the entire side over here. I just said we're going to monitor the gas flow reading because notice this is actually multiple requirements over here. You're going to monitor the gas flow reading. You're going to calculate and display the ongoing gallons and the price. So there's multiple requirements here and we want each product level requirement to be a single unique requirement. So to expand on that and look at the rest response, we're going to display the gallons pumped and we're going to use that same template over again. But now for the first one, when the gas flow control hardware is pulled, the latest gas cumulative gas amount of gas pumped, then the system shall calculate the gas price by multiplying the latest cumulative amount of gas pumped by the cost per gallon for the grade of gasoline being pumped. Notice we've got two more data item names here. The amount of gas pumped and the cost per gallon for the grade pumped. And we're telling the programmer exactly how to calculate the price. And then there's two more. There's. There's actually three things that are being done each time you pull the hardware. And you can have three requirements. Of course, now you start having lots of redundancy. I recommend you combine those. I love bulletized requirements. I am, maybe I'm a lazy reader, but I don't want to read any more than I absolutely have to. And it also, by rolling it up this way makes it very specific that there's a single input or event condition that causes three things to happen. So when the gas flow control hardware is pulled for the latest cumulative amount of gas pumped, the system shall do each of these three things. Now notice these don't have any particular order. If there was an order, then I would add the word and you know, something like chain these together by saying the system shall do this, then do this, then do this. So you can add order to these when you are doing it, if appropriate. But this starts breaking those steps in the use case down into the detailed product level requirements. So this is just one of many tools that can be used. Pick the tool that works best for you and the people you're trying to elicit information from at the stakeholder level. The other reason I do these is they're fast and easy. So you can get a lot of information in a short time with these. Then looking at one of the alternative steps, identify the system identifies an error. Comfortable. Go back to the previous format where we bulletized it, in which case requirement 11 to 112.1 becomes displaying the error message and 112.2 becomes re prompting for the gas type. That way you've got two specific requirements that are sub requirements under the if statement. So this almost becomes a matter of form. You know, would you consider that one or two? I consider it one because I'm just going to write a single test case for this with two expected outputs. But if you would do it as two test cases, write it as sub bullets. So that handles the functional requirements and gives you some examples. Now let's talk about data requirements down at the product level. Data requirements are very specifically what pieces of data are you going to create? Update, read, list, display, whatever. So I go back to my functional level requirements and look for those nouns and I've made them very specific because I italicize them and I say, is this a data item that I need to deal with in the system? Is this a data item? Is this a data item? Now there may be some nouns that aren't. For example, when I talk about the customer, I would probably not be keeping any data information about the individual customer, but I might have transaction information, whatever. So when I look at these nouns, then I go and ask myself, do I need to have functional requirements around creating, updating, reading, deleting and listing these? I use the CURTL acronym here. And what this is helping me do is look for completeness in my requirements. Have I missed anything? Because going through those use cases, I might not have use cases, for example, for creating a new gas price, I might not have thought of it as an interaction with the owner of the gas station or updating the gas price. So just for completeness sake, I look for those nouns in my requirements and then say, do I need to create a new gas price for the type of gas being pumped? Am I ever going to do that? Do I have requirements defined? Am I ever going to update the gas price? Well, yeah, that's probably happening regularly. In which case I am going to make sure I have those requirements defined. If I don't, then I've got more requirements to add. Am I ever going to read it? This would be things like being able to display it out at the pump. In fact, you mentioned business rules. There's government regulations in our business rules and there are government regulations that say you have to display the price, the current price of gas out at the pump. Am I ever going to list it? On some kind of report. For example, do I need a report that trends this over time? Now by doing this, this is reminding me potentially to go back and ask the stakeholders, do you need a report like this? So this is going to help me with trying to get my requirements as complete as I possibly can. I also have non functional requirements down at this level. Now we mentioned business rules briefly. Business rules are all about the rules for running your business. These may be like we talked about government regulations. They also might be the rules of the actual business. For example, you can pump no more than $100 per transaction, no more than two transactions on the same credit card per day. And those are going to flow into non functional requirements or maybe even into quality attributes. And quality attributes are things. Have you ever had your customers or your users say I want it to be fast? Well, what's fast? I don't know how to program fast. And you're going to have to feed that down as a business analyst or requirements analyst down into specific non functional requirements that define how fast is fast. Now, non functional doesn't mean they're non functioning folks. It means that they are not specific to any given feature or function. They tend to cross multiple functions. For example, fast might relate into all user interactions will be responded to within three seconds, even if it's with that little floating dot or something like that, just to let them know that something's going on. So three seconds might be fast. Have you ever had somebody ask you to have it be user friendly? Well, that might translate into functional requirements of having a help function and all of the associated product level requirements around being able to ask for help and get that help. Or it might translate down into non functional requirements. For example, the display can be read by somebody with 2030 vision from so many feet away and so many luminas of light. That's one of my pet ones because I've gone to the gas stations that have the dark gray back light gray background with the dark gray letters that cannot be read in the bright sunshine. Have you ever seen people sitting there holding their hands over the screen just trying to read it? That's not very user friendly or just simply having the cancel button. One of mine that I would love to have is go back one step button or a back button because I've been to gas stations where all of a sudden it's asking me for a car wash and I accidentally hit the wrong button. Now I have to cancel completely out and go all the way back to scanning my credit card and re entering my pin and doing all the other prompts instead of being able to just go back one step and say no, I don't want it, instead of yes I do. So those kinds of things might be user friendly. So for each of your use cases you may have quality attributes that apply to the whole use case. For example, how quickly can I pump gas out at the pump, start to finish? Or how user friendly that whole interaction is. You may have ones that apply to specific steps or apply to multiple functional requirements. Remember, if it's specific to a single function, then it would just be part of that functional requirement. Like to poll the gas pump once every tenth of a second. I don't need a separate requirement to say that polling happens once every tenth of a second. I can fold that right into the functional requirement, how fast that needs to be because it's unique and specific just to that polling. But if it's something like all monetary calculations will be rounded to the nearest penny, then it will relate to all the functional requirements that are doing cash based calculations. So it's going to apply to several of them. And those quality attributes then become the non functional requirements. And there are many, many different quality attributes that you may be dealing with. They include all of these. Reliability, availability, performance, all of those kinds of things. To spend the time defining each and every one of these. You can get definitions of these in many of the product literatures, but let's talk about writing some product level requirements for these. For example, for reliability, we're going to monitor the gas flow and calculate and display the ongoing gallons. Here reliability is all about failures in time. Either mean time to failure or the number of failures per period of time. So from Gilb's work I've come up with a template. What's the mean time for a defined product or product component to experience a defined type of failure under? Typically this is things like under normal operating conditions or under some other special conditions. But obviously if there's a power outage in the neighborhood that would not be normal operating conditions. Your system is down not through any fault of its own, but simply because it's hard to run software without electricity. So we're talking about under normal operating conditions. And we can simply define then associated with this step a meantime of 30,000 hours for a gas flow control hardware component to experience a failure to read the gas flow error under normal operating conditions. So there's an example availability. For some reason this has gone off the screen. I have no idea why availability is talking adds recoverability to the reliability concept. So now it's not how many outages we had, but the duration of those outages or the time. Usually it's defined in the percentage of time that a defined product is not available or will be available for use under defined conditions. Now we'd all love to say 100% of the time the system is going to be available, but that's just not realistic. So what is realistic? The pump will experience no more than an average of 3 minutes of unplanned outage during a 12 month period or whatever. Or you can talk about the defined product or product component will experience an average or a maximum amount of time of a defined failure type during a time period. So those are my templates for the availability of a system. Performance Requirements Dynamic part of your system might be a capacity requirement is the quantity of things that can happen at the same time. Throughput is the quantity of things that can happen in a period of time. For example, throughput might be 100 gas station pay at the pump. Transactions can be successfully handled per per hour or capacity would be things like up to 30 gas pumps can be processing gas purchases at the pump at the same time. That would be an example of a capacity 1. Response times are also performance requirements. The mean time or average time of a defined response. Again, it will require no more than a maximum of three seconds from the time a message is sent to the attendance or a pump display to display that message. No more than three seconds. So you're talking about. Remember when you talk about response time requirements, always make sure they are things that you have control of. Otherwise you have requirements that are untestable and non feasible. An example of this I actually worked on a system once and our requirement was the report will be processed in no more than 30 seconds. Well, we assumed that meant from the time it entered our system until the time we posted it out on the customer's network to be printed and it was taking on average about 10 seconds, never took more than 15. We were way below the 32nd requirement, but we didn't specify the specific from where to where measurements of this. Notice this one says from the time the message is sent to the attendant until it's displayed. Gives the boundaries here because our customer interpreted that metric, that requirement as from the time they entered the command until the report was sitting on the printer waiting for us to print. And that took up to 10 minutes because their network was so very very slow and so under capacity. So when you're writing response time requirements, performance requirements, be sure you're very specific about not only the Specific time. Instead of saying quickly, say three seconds. But also make sure you're talking about from where to where you're measuring and make sure that's within the scope of your system. For example, I cannot on the Gaspay system, my system is not under the control of how quickly the bank responds to requests. So I can't have performance requirements around how quickly it validates credit cards. That may take more than you know, it's out of my control as a system, so I can't test that, I can't control that. But I can control how quickly my system will timeout if it does not get a response. So I can have requirements around if it does not receive a response within X number of minutes. The system will do what So I can have those types of requirements now Usability requirements Examples of templates Here we can talk about the ease of learning how much time or effort. You know, it might be no more than a two week class or no more than 40 hours of training required to become proficient in a particular task or action. That is to be able to do all of the reporting out of the GASP system or to be able to be an attendant and adequately run the system. And again, under normal defined conditions and this may assume certain things about the person that's using it. For example, are they even literate or at what level of literacy are we expecting our users to be? And you may want to define that, of course, when it goes back to illiteracy. Do you want illiterate people to be able to buy gas from your gas station or people that don't speak English? And we're back into usability for people that are illiterate or English, non English speaking. Have you noticed that more and more of the gas stations have little pictures that demonstrate what to do, little animation as well as just the words. And again, that gets back into usability for those non English speaking or illiterate people. You can talk about the productivity now it's not the productivity of the system, it's the productivity of the people using the system. So the quantity of defined tasks or actions that can be performed using this per time period under again specific defined conditions, which may mean something like they've been trained, they have their training response time. Now we're talking about response time of the system to the user Error rates, what number of errors will the user typically do? For example, 98% of users will be able to enter their credit card into the system in the correct manner. You know I'm left handed, the picture always has my thumb on the wrong side. And I've seen more and more systems now that have a picture on the left for the left handed person and a picture on the right for the right handed person so that they have their thumb on the right side of the card when they're putting it in. Or you could have multiple heads on the card reader, whatever. And even things like likability, the quantity or percentage of users that report they like the product on a customer satisfaction survey or something like that. Asq, when I teach training courses for them, actually grades me and I have to have a certain score in the top two boxes on my satisfaction surveys. So these would be examples of usability requirements. When you're looking security, we're now looking at the probability that an attack on the system will either not be able to get into the system at all, we'll keep it out, or if it does get into the system, it can't do damage. Or at least we can recover from whatever damage they do. Or at a minimum we have some kind of audit trail that records what's happening when so that we can determine how the security breach happened to prevent future reoccurrences, you know, whose password got compromised, or whatever. So here's a list of templates for those types of requirements. Again, you may look at the different steps in your use case and say do I need any security requirements at any of these places? So it might be the probability that a defined product or product component shall handle by either detecting, preventing or recovering from a defined attack under again, typically normal operating conditions. So this might be include things like firewalls or passwords for detecting even biometrics. Prevention might include things like encryptions or even different levels of privilege. So even if you break in, you don't have the privilege to do certain things like change the price of gas, those kinds of things, or at least recover from again, this might be requirements around backing things up, or it might be having a virus detection and or recovery system built into your software. Another security requirement, the system shall either lock or place out of service an external ask access under a particular number of unsuccessful attempts to log in, handshake or authenticate within a particular period of time. Again, for the pay at the gas pump system. For a debit card, we're not going to allow them more than three attempts to put in their PIN number. If they put it in wrong three times in a row, it's going to lock that card out for some period of time or until a particular maybe the bank, you have to call the bank and get it revalidated or unlocked. The system shall log all attempts to access secure data, perform specific functions by users having insufficient privileges. This is your audit trail. And finally, the system shall timeout, logout, lockout, access to a particular data asset or function after a particular period of time of inactivity. For example, I go up to the pump, I scan my card, I get in my car and drive away. Well, we don't want that card hanging out there for too long. Maybe if the user does not respond within 30 seconds to the next prompt, it will lock it out or cancel that transaction. Go back to idle mode would be examples of those types of security requirements. Finally, let's talk briefly about safety requirements. The system shall prevent, detect, report or react to a particular type of failure such that a particular type of accident is prevented under normal operating conditions. So for example, your pay at the gas pump, if it you know, it's going to detect whether it's overflowing gas and turn the gas off so that it won't dump gas all over the ground. The system shall not cause more than an average number or maximum number of specific safety incidences per period of time. The system shall not allow a safety risk to exceed a specific level or variance. For example, we may shut the gas off after it's pumped 50 gallons, because nobody's going to ever pump more than 50 gallons. Or at least they have to take some kind of physical override on that. For example, I do have a hundred gallon gas tank in my car, but maybe it shuts it off every 30 gallons and makes me restart the hand, you know, by recompressing the handle. The system should act to a particular type of accident by performing a particular type of action. This is again something like I'm going to get off the gas station thing. But your sprinkler system, if it detects so many, so much amount of smoke in the air, it will turn the sprinkler system on. Or your airbags in your car, if it detects a certain level of impact, it's going to send your airbags going off. And the system shall prevent, detect or react to a particular type of accident a particular percentage of time. So those are all examples of safety type requirements. So we've talked about functional data and non functional requirements. Let's talk about interface requirements. I go back to that use case diagram and every place that a actor's arrow crosses the boundary of the system may be a place where you want to put interface requirements in place. Now, to a user, those may be particular interface requirements around style, color, font sizes, readability, all those kinds of things to particular other software packages. These may be external protocols, formats, how to interpret the particular signals that are coming in and out, those kinds of things. But wherever you see those things crossing the line, that may be an indicator that there needs to be external interface requirements to your system. And of course, if you have a higher system level architecture where you actually have this piece of software on, this piece of equipment and these pieces of software within this server and computer and out at the pump you have the card reader with its software and the pump with its software. And wherever these software packages talk to each other, internal to your system or where they are talking to the hardware that they are interfacing with, all of those are examples of where you may need to define interface requirements. And at that we will end the webinar. Thank you very much.