Writing useful Use Cases
-
We're starting a new project at work, and have recently entered the documentation phase. A detailed functional requirements doc has been created and reviewed. Now we're starting to write use cases. I was wondering if anyone out there might have some good suggestions for how to create use cases that are actually going to be helpful later on (in the Design and Implementation phases). I'm fortunate enough to have the luxury of time to actually write real documentation for the project, so I want to be sure that what I write will help us out in the long run. Any tips? Thanks.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
-
We're starting a new project at work, and have recently entered the documentation phase. A detailed functional requirements doc has been created and reviewed. Now we're starting to write use cases. I was wondering if anyone out there might have some good suggestions for how to create use cases that are actually going to be helpful later on (in the Design and Implementation phases). I'm fortunate enough to have the luxury of time to actually write real documentation for the project, so I want to be sure that what I write will help us out in the long run. Any tips? Thanks.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
Some thoughts: Start by writing a use case for each functional requirement. This should be the simplest use case possible to test the functional requirement. Make notes as you write the use cases regarding other ideas you have for more complicated functional tests. You can then write additional use cases later. The use case document isn't a "do it once" thing. As you develop, test, and debug, you need to update the use cases to cover new and more complex things. But what happens is that the use case document becomes an acceptance test document. You may want to think about whether you want them to be the same or different. For example, an ATP might be considerably more rigorous, whereas the use case might only cover the "typical" user (like the user that leaves the advanced menu options off in Office). What this means though is that you will need to go back to your functional requirements doc and decide what falls under typical user functionality and what might be considered, say, a power user. The other thing use cases are good for is testing the limits of your application in terms of usability. This may involve using the app in conjunction with another app. For example, you could come up with an Office use case that involved exporting data from Access, importing it into Excel, creating a graph, and emailing it to a mailing list generated by, say, Sage Fundraiser. Your use case falls into the category of flexibility. :) Marc
-
Some thoughts: Start by writing a use case for each functional requirement. This should be the simplest use case possible to test the functional requirement. Make notes as you write the use cases regarding other ideas you have for more complicated functional tests. You can then write additional use cases later. The use case document isn't a "do it once" thing. As you develop, test, and debug, you need to update the use cases to cover new and more complex things. But what happens is that the use case document becomes an acceptance test document. You may want to think about whether you want them to be the same or different. For example, an ATP might be considerably more rigorous, whereas the use case might only cover the "typical" user (like the user that leaves the advanced menu options off in Office). What this means though is that you will need to go back to your functional requirements doc and decide what falls under typical user functionality and what might be considered, say, a power user. The other thing use cases are good for is testing the limits of your application in terms of usability. This may involve using the app in conjunction with another app. For example, you could come up with an Office use case that involved exporting data from Access, importing it into Excel, creating a graph, and emailing it to a mailing list generated by, say, Sage Fundraiser. Your use case falls into the category of flexibility. :) Marc
Thanks a lot, Marc. You definitely put some helpful/insightful thoughts into my mind. I have a follow-up question, if you don't mind. What is an "acceptance test document"? I've never heard of that before. At what point during a project's lifecycle is that doc used? Thanks again.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
-
Thanks a lot, Marc. You definitely put some helpful/insightful thoughts into my mind. I have a follow-up question, if you don't mind. What is an "acceptance test document"? I've never heard of that before. At what point during a project's lifecycle is that doc used? Thanks again.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
Josh Smith wrote:
What is an "acceptance test document"?
Heh - I'll take a stab at that one - given that part of our software development process is a documented user acceptance test. We use an iterative delivery process, so we deliver multiple 'betas' (for want of a better word). When we and the customer are approaching happiness with the product, the customer is expected to perform tests on the product that show whether or not their requirements are met. The documentation for this consists of a test plan (i.e. what are we going to test, and why) and a test report (i.e. did the software pass the tests), usually rolled into one document. This is their acceptance test document. If the acceptance test is all passes, everyone's happy. If not, then we'll either do a bug-fix delivery (and the customer performs the acceptance test again), or deliver the software with known issues - we'll only do that for relatively obscure failures, though. To summarise - the acceptance test report is a statement that the software is of acceptable quality to be used by the customer. HTH!
-
Thanks a lot, Marc. You definitely put some helpful/insightful thoughts into my mind. I have a follow-up question, if you don't mind. What is an "acceptance test document"? I've never heard of that before. At what point during a project's lifecycle is that doc used? Thanks again.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
Josh Smith wrote:
What is an "acceptance test document"? I've never heard of that before. At what point during a project's lifecycle is that doc used?
Google "acceptance test procedure". It's a document that everyone agrees on that tests functionality to meet say, a milestone delivery. It can be used for regression testing after a product is released. Think of it as a manual (usually) but more comprehensive unit testing. For example, a unit test might have a hard time figuring out if a control accepts drag & drop, or if an error message is displayed in red, or if the battery backup sends the correct signal to the computer when the main power is disrupted. An ATP will cover the things unit testing (like is the workflow logic actually correct and does it result in the right decisions) that unit testing can't. Marc
-
Josh Smith wrote:
What is an "acceptance test document"?
Heh - I'll take a stab at that one - given that part of our software development process is a documented user acceptance test. We use an iterative delivery process, so we deliver multiple 'betas' (for want of a better word). When we and the customer are approaching happiness with the product, the customer is expected to perform tests on the product that show whether or not their requirements are met. The documentation for this consists of a test plan (i.e. what are we going to test, and why) and a test report (i.e. did the software pass the tests), usually rolled into one document. This is their acceptance test document. If the acceptance test is all passes, everyone's happy. If not, then we'll either do a bug-fix delivery (and the customer performs the acceptance test again), or deliver the software with known issues - we'll only do that for relatively obscure failures, though. To summarise - the acceptance test report is a statement that the software is of acceptable quality to be used by the customer. HTH!
Stuart Dootson wrote:
To summarise - the acceptance test report is a statement that the software is of acceptable quality to be used by the customer.
Exactly! Though it should be stated that one can be one's own customer--meaning, the ATP can be used internally as well. Marc
-
Stuart Dootson wrote:
To summarise - the acceptance test report is a statement that the software is of acceptable quality to be used by the customer.
Exactly! Though it should be stated that one can be one's own customer--meaning, the ATP can be used internally as well. Marc
Marc Clifton wrote:
one can be one's own customer
Quite true - also, when delivering software under that regime, I try to make sure I have a functional test suite that matches my idea of what's acceptable to the customer. As most of my software is command-line driven apps (or at worst, a GUI with a sneaky command-line interface), it's relatively painless to do functional requirements testing. And that way, I can be pretty confident that my software will pass an acceptance test (or at least the major part of one) before I pass it to the customer.
-
Josh Smith wrote:
What is an "acceptance test document"?
Heh - I'll take a stab at that one - given that part of our software development process is a documented user acceptance test. We use an iterative delivery process, so we deliver multiple 'betas' (for want of a better word). When we and the customer are approaching happiness with the product, the customer is expected to perform tests on the product that show whether or not their requirements are met. The documentation for this consists of a test plan (i.e. what are we going to test, and why) and a test report (i.e. did the software pass the tests), usually rolled into one document. This is their acceptance test document. If the acceptance test is all passes, everyone's happy. If not, then we'll either do a bug-fix delivery (and the customer performs the acceptance test again), or deliver the software with known issues - we'll only do that for relatively obscure failures, though. To summarise - the acceptance test report is a statement that the software is of acceptable quality to be used by the customer. HTH!
Stuart Dootson wrote:
To summarise - the acceptance test report is a statement that the software is of acceptable quality to be used by the customer.
Thanks for the info, Stuart. I understand what you're getting at. I can see how Marc's use case suggestions fit in with that idea. This is a very informative thread, thanks to you and Marc! :cool:
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
-
Josh Smith wrote:
What is an "acceptance test document"? I've never heard of that before. At what point during a project's lifecycle is that doc used?
Google "acceptance test procedure". It's a document that everyone agrees on that tests functionality to meet say, a milestone delivery. It can be used for regression testing after a product is released. Think of it as a manual (usually) but more comprehensive unit testing. For example, a unit test might have a hard time figuring out if a control accepts drag & drop, or if an error message is displayed in red, or if the battery backup sends the correct signal to the computer when the main power is disrupted. An ATP will cover the things unit testing (like is the workflow logic actually correct and does it result in the right decisions) that unit testing can't. Marc
Marc Clifton wrote:
Google "acceptance test procedure".
Why Google it, if I can "Clifton" it? Just kidding. :laugh: I understand what you mean now. Thanks. I have been involved with User Acceptance Testing before, so I'm familiar with this concept. I had not, however, had a document to distribute to users. That's a great idea!
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
-
We're starting a new project at work, and have recently entered the documentation phase. A detailed functional requirements doc has been created and reviewed. Now we're starting to write use cases. I was wondering if anyone out there might have some good suggestions for how to create use cases that are actually going to be helpful later on (in the Design and Implementation phases). I'm fortunate enough to have the luxury of time to actually write real documentation for the project, so I want to be sure that what I write will help us out in the long run. Any tips? Thanks.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
Josh Smith wrote:
We're starting a new project at work, and have recently entered the documentation phase. A detailed functional requirements doc has been created and reviewed. Now we're starting to write use cases. I was wondering if anyone out there might have some good suggestions for how to create use cases that are actually going to be helpful later on (in the Design and Implementation phases).
Take a look at the material at: http://alistair.cockburn.us/index.php/Main_Page[^] esp. http://alistair.cockburn.us/index.php/Resources_for_writing_use_cases[^]
-
Josh Smith wrote:
We're starting a new project at work, and have recently entered the documentation phase. A detailed functional requirements doc has been created and reviewed. Now we're starting to write use cases. I was wondering if anyone out there might have some good suggestions for how to create use cases that are actually going to be helpful later on (in the Design and Implementation phases).
Take a look at the material at: http://alistair.cockburn.us/index.php/Main_Page[^] esp. http://alistair.cockburn.us/index.php/Resources_for_writing_use_cases[^]
Roland Pibinger wrote:
Take a look at the material at: http://alistair.cockburn.us/index.php/Main\_Page\[^\] esp. http://alistair.cockburn.us/index.php/Resources\_for\_writing\_use\_cases\[^\]
Thanks. That looks like very thorough material. I'll check it out tonight.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
-
We're starting a new project at work, and have recently entered the documentation phase. A detailed functional requirements doc has been created and reviewed. Now we're starting to write use cases. I was wondering if anyone out there might have some good suggestions for how to create use cases that are actually going to be helpful later on (in the Design and Implementation phases). I'm fortunate enough to have the luxury of time to actually write real documentation for the project, so I want to be sure that what I write will help us out in the long run. Any tips? Thanks.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
It's not that easy to offer use cases, when you don't know what the user will be using. What's the target industry, what sector(s) of the industry will be using it, and which departments of the companies in the sector(s) is it aimed at?
-
It's not that easy to offer use cases, when you don't know what the user will be using. What's the target industry, what sector(s) of the industry will be using it, and which departments of the companies in the sector(s) is it aimed at?
Mark Wallace wrote:
What's the target industry, what sector(s) of the industry will be using it, and which departments of the companies in the sector(s) is it aimed at?
I can't give specific info because I'm working on a product. It's not for employees of a company. It's for the general public. I work for the New York Times, so assume that it has something to do with reading the news. :)
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
-
Mark Wallace wrote:
What's the target industry, what sector(s) of the industry will be using it, and which departments of the companies in the sector(s) is it aimed at?
I can't give specific info because I'm working on a product. It's not for employees of a company. It's for the general public. I work for the New York Times, so assume that it has something to do with reading the news. :)
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.
Josh Smith wrote:
I can't give specific info because I'm working on a product. It's not for employees of a company. It's for the general public. I work for the New York Times, so assume that it has something to do with reading the news.
I get this quite often. There is all manner of theoretical crap about (academics have nothing better to do with their time) on how to construct use cases, but the key (and, by "key", I mean "abso-f***ing-lutely can't be done without!) element required to construct a use case is knowledge of the user. You need to know what the user will be doing with your software, not guess, based on what you might want to do with it. I know you're probably smart; you might even be the cleverest person I've ever talked to, but your world view, as a developer, and your way of doing things/using things will not be the same as your users' world view and way of doing things/using things, so you shouldn't even consider trying to decide how end users will be using what you develop (I'll bet that not one of them wants to use command-line tools, for example). If you have a PR department, as them for use cases; they can go straight to the horse's mouth. If you haven't, give me an idea of who your users might be, and what they'll be using, and I'll knock up some use cases (take it off-line, if you like; my e-mail's stored somewhere around here).
-
Josh Smith wrote:
I can't give specific info because I'm working on a product. It's not for employees of a company. It's for the general public. I work for the New York Times, so assume that it has something to do with reading the news.
I get this quite often. There is all manner of theoretical crap about (academics have nothing better to do with their time) on how to construct use cases, but the key (and, by "key", I mean "abso-f***ing-lutely can't be done without!) element required to construct a use case is knowledge of the user. You need to know what the user will be doing with your software, not guess, based on what you might want to do with it. I know you're probably smart; you might even be the cleverest person I've ever talked to, but your world view, as a developer, and your way of doing things/using things will not be the same as your users' world view and way of doing things/using things, so you shouldn't even consider trying to decide how end users will be using what you develop (I'll bet that not one of them wants to use command-line tools, for example). If you have a PR department, as them for use cases; they can go straight to the horse's mouth. If you haven't, give me an idea of who your users might be, and what they'll be using, and I'll knock up some use cases (take it off-line, if you like; my e-mail's stored somewhere around here).
Mark Wallace wrote:
If you have a PR department, as them for use cases; they can go straight to the horse's mouth.
Thanks Marc. That makes sense.
:josh: My WPF Blog[^] FYI - Bob is a scarecrow who keeps Chuck Norris away from CodeProject.