Writing Effective Use Cases

Alistair Cockburn

Mentioned 13

This guide will help readers learn how to employ the significant power of use cases to their software development efforts. It provides a practical methodology, presenting key use case concepts.

More on Amazon.com

Mentioned in questions and answers.

I was wondering if anyone could provide me some information on what they put in a requirements document, how do you structure it? I'm the lead for the first time ever and I want to make sure I provide good documents so the project will succeed.

Any templates/examples would be great.

This is a somewhat deep question, so I am hesitant to give a short answer. It is a good idea to read a few good books that describe different approaches, such as The Inmates Are Running the Asylum, which describes scenario-based function design. Another approach is to use high-level use-cases, as described in Writing Effective Use Cases.

Some guidelines:

  • Write what is required without constraining how this will be done.
  • Make each requirement a separate numbered list entry for cross-reference.
  • Split requirements into separate items until each one is 'atomic'.
  • Include a Security section, and be explicit about what security is required.
  • Include a Non-functional requirements section, for constraints like performance and availability.
  • Include a Non-requirements section to list things that are not requirements, so you can tell the difference between something you forgot, and something you do not need.
  • Specify external interfaces (to other systems) as well as user-interface requirements.

Karl Wiegers, author of Software Requirements and More About Software Requirements also has a website called Process Impact. Although most of the stuff is for sale, you should check out the Goodies section, which has documents that are released for the nominal sum of $5. One of the files that you can download is a set of Sample requirements documents, including a vision and scope document, use cases, software requirements specification (SRS), business rules, data dictionary, and some analysis models for a small information system (ZIP file). You can also find templates for a number of requirements documents.

If you have the money, I would recommend both books. If you don't want them, maybe your company can buy and own them if there is a company library or something like that. Either way, they are must-reads for anyone working on requirements gathering/analysis.

I would love to hear ideas on how to best move code from development server to production server.

A list of gotcha's, don't do this list would be helpful.

Any tools to help automate the steps of.

  1. Make backups of existing code, given these list of files

  2. Record the Deployment of these files from dev to production

  3. Allow easier rollback if deployment or app fails in any way...

I have never worked at a company that had a deployment process, other than a very manual, ftp files from dev to production.

What have you done in your companies, departments, etc?

Thank you...

Yes, I am a coldfusion programmer, but files are files, and this should be language agnostic question.

OK, I'll bite. There's the technology aspect of this problem, which other answers have already covered. But the real issue is a process problem. Where the real focus should be ensuring a meaningful software development life cycle (SDLC) - planning, development, validation, and deployment. I'll cover each in turn. What you want is a repeatable activity at each phase.

Planning

Articulating and recording what's to be delivered. Often tickets or user stories are enough. Sometimes you do more, like a written requirements document, that a customer signs off on, that's translated into various artifacts such as written use cases - ultimately what you want though is something recorded in an electronic system where you can associate changes to code with it. Which leads me to...

Development

Remember that electronic system? Good. Now when you make changes to code (you're committing to source control right?) you associate those change with something in this electronic system - typically tickets. I like Trac, but have also heard good things about Atlassian's suite. This gives you traceability. So you can assert what's been done and how. Then you can use this system and source control to create a build - all the bits needed for whatever's changed - and tag that build in source control - that's your list of what's changed. Even better, have a build contain everything, so that it's standalone entity that can easily be deployed on it's own. The build is then delivered for...

Validation

Perhaps the most important step that many shops ignore - at their own peril. Defects found in production are exponentially more expensive to fix then when they're discovered earlier in the process. And validation is often the only step where this occurs in many shops - so make sure yours does it.

This should not be done by the programmer! That's like the fox watching the hen house. And whoever is doing is should be following some sort of plan. We use Test Link. This means each build is validated the same way, so you can identify regression bugs. And, this build should be deployed in the same way as you would into production.

If all goes well (we usually need a minimum of 3 builds) the build is validated. And this goes to...

Deployment

This should be a non-event, because you're taking a validated build following the same steps as you did in testing. Could be first it hits a staging server, where there's an automated copying process, but the point being is that is shouldn't be an issue at this point, because you validated with the same process.

Conclusion

In terms of knowing what's where, what you really want is a logical way to group changes together. This is where the idea of a build comes in. It's really the unit that should segue between steps in the SDLC. If you already have that, then the ability to understand the state of a given system becomes trivial.

I am a bit confused about where to describe the algorithm I might use in some part of an application.

Let's say I want to create a Use Case that describes how the User inputs a set of values and my application returns the average of those values (of course this is a dead-easy case, but its easier to explain it this way).

1. The User tells the System he wants to calculate the average of a set of numbers.
2. The System asks the User for a number.
3. The User tells the System a number.
Repeat steps 2-3 until the User tells the System there are no more numbers left.
4. The System returns the average of all those numbers.

Now, where should I state the algorithm behind calculating the average of the numbers?

What if instead of calculating the average of numbers, I had to change the configuration of a game, go to the next level, add users to a database given a set of conditions, etc?

I feel like I need to in some way formalize the knowledge I have of the domain, otherwise I might either forget it or even worse, assume I know things that only by writing down would I understand I don't.

In other thread, topic, someone talked about business rules. From what I've read they seem to be put as small notes on class diagrams. Maybe I'm wrong? If that's what they are, I find they too cumbersome to use for more complex algorithms.

Thanks

If you really want to stick with Use Cases you'd write one from the System's functional viewpoint rather than that of the end-user. Maybe something like this:

  1. The systems starts up and zeros out its total and count variables.
  2. The system receives a number.
  3. It adds the number to the total and increments the count.
  4. Steps 2 & 3 repeat until the system is told to stop.
  5. When told to stop the system divides the total by the count and returns the result.

Have a read of Alastair Cockburns excellent book "Writing Effective Use Cases". It explains about having different levels of Use Case. Your initial example would be considered a User Goal (or Blue) Use Case whilst the steps above would be part of a Sub-Function (or Indigo) Use Case (it's so simple it might even be classed as a Black Use Case and just merged into its parent).

As other people are sure to say, sometimes a Use Case isn't the best way to describe an algorithm and you should fall back to good old flowcharts, state charts, sequence diagrams or whatever. These tools are there for your benefit - don't be constrained by forcing a particular method when it doesn't work for you.

EDIT

@devoured elysium: In response to your comments I've added a few more notes below:

When you're identifying domain objects sometimes you need to think about unwritten objects. It all depends on how it has been written. So, in the example you gave, maybe the "System" is a "Calculator", the variable being used to add the numbers up is an "Accumulator", maybe there's a "Queue" that receives the number. Could be that the number itself is an object of a type "Number" if that can have distinct behaviour like range validation, or input syntax checking. Is there a "Display" object that you need to consider?

It depends on what you consider to be in the bounded context you're dealing with. Maybe, from the User's perspective, there is one context that just deals with "Calculators", but the System's viewpoint there's another that speaks to a lower lever context with "Accumulators", "ALUs", "Bits", "Words", "Registers", "Clocks", "Latches", etc. The further you go down in the Use Case heirarchy by asking "How?" the more technical the language is going to become. You need to decide which are Domain Objects and which are just Implementation Objects and that depends very much on the type of thing you're trying to describe and build (and, to a great extent, who your audience is - ubiquitous langauge and all that!). Conversely, you can go up the stack by asking "Why?" the function is being performed.

The primary actor of a Sub-Function Use Case is generally the same actor as that of the higher-level use case that calls it. For some "technical" Use Cases though, the primary actor will be a system component/subsytem. For example, a system message logging Use Case might have the calling subsystem as the primary actor - i.e. the entity that had the will/need to initiate the action, rather than the actor that was performing the task that caused that subsytem to need to log something.

In this example, where the algorithm is so simple, I'd probably just Embed it into the main Use Case. However, if it was being used in multiple other higher-level Use Cases I'd make it Standalone so I could include it from the other documents. Just a functional decomposition approach.

There are no hard-and-fast rules with this. It's a style of working that you'll evolve over time. As others have said, make sure that you're familiar with the other forms of diagrams so that you can pick the right tool for the job. Remember that although a picture may be worth a thousand words sometimes you actually need those words too so don't just rely on diagrams.

I am new to writing use cases.I heard that Use cases are non-technical expressions .

I have the following task for which i have to write Use case.
(I reduced the requirement for your understanding)

Registered Customer of ABC company logged in to the system with credentials to retrieve the complete Address of particular service provider.He searches the service provider on TextBox.The System communcates with database and displays the result on monitor.

I am technical guy,
I have to write use case to explain the behavior of the system to the client.

I have written Use case as follows :


Use case Name: Address Locating System
Primary Actor: Customer
Stakeholder: ABC Company
Precondition: Customer Successfully Logged in to the system

Success Scenarios:

  1. Customer Enter the search term in the box provided.
    • System searches the search terms for matches.
    • System Supplies the address to the Customer.

Extension Point: Client is informed when no successful match
Post condition: None


Questions.

  1. Is the Use Case described above, correct?
    • Do really tech people need to write Use cases?

Whenever I need to write a Use Case, I pick up my copy of UML Distilled and use its suggested format. There are variations in the formats, so this isn't the only way. In any case it's a good reference to have on your desk. You might also check out Writing Effective Use Cases; I haven't read that one, though.

If you'd like a free example, see:

http://ontolog.cim3.net/cgi-bin/wiki.pl?UseCasesMartinFowlerSimpleTextExample

I might avoid the "in the box provided" bit - that's an implementation detail that might change. I might also change 2 to just "System searches for matches."

And yes, technical people do need to write Use Cases readable by non-technical domain experts.

Could you suggest a comprehensive use-case tutorial? I would like something which would explain how to organize use case diagrams in packages, relationships in UC diagrams.

This is the best book I know about use cases.

Writing Effective Uses Cases

What are the steps to be followed when we start UML diagrams for new features or requirements?

I need the entire steps like

  1. Identify the actor,
  2. Identify the use cases,
    like this etc....

This is a very board expression. In general, I would start with Use Case diagrams and go from there. As Gabriel pointed out, there are entire books written on this and there is no one right answer. My personal favorites for Use Cases are:

Advanced Use Case Modelling

and

Writing Effective Use Cases

Suppose I have a use case buy book, and the main flow is the following:

1- The user types the book code that he wants to buy
2- The system replies that there's enough stock of the requested book
3- The user confirm

Very simple.

Now suppose I want to give the option to the user to also do another thing between 2 and 3. How should I say it? I guess it's an extension to this use case, but I'm not sure where it's the point of extension.

As far as I know, if I choose, say, point of extension in 3, then the user has the opportunity to do 3 or do all the extension but not 3. The same behaviour of alternative flows.

But what I want is different. I want some "2.5" or nothing... do it or do nothing instead; not another thing.

I'm sorry for the vague question.

One option is the format recommended in Alistair Cockburn's Writing Effective Use Cases:

2a-  User wants to do another thing:
2a1- The user does another thing
2a2- The system responds in some way, returns to step 3

Step 2a occurs after step 2 and before step 3. If the UC ends at step 2a2 then simply replace 'returns to step 3' with 'Use Case ends' or similar.

hth.

we discuss the way to write technical realization concepts for web applications wich will be created with PHP5 + Zend Framework.

The Goal is an concept for an developer to create the application. So that someone with minimal knowledge about our company is able to start coding.

Example (short!):

Requirement: Create an Application to Post news to the company webpage. There must be a way to create, edit, delete news from the frontend for registered users.

What do you put into such an concept if you arent the guy who will code it?

Or in simple words:

What kind of documents do you create before you start writing source code :-)

When you are introducing someone new to your programming environment they need to understand the business problems as opposed to the technical. For the feature set under consideration, you need to identify the expected success paths and minimize the failure space before handing off to them. By this I mean clearly documenting how a particular piece of functionality is expected to behave and also what should happen when something is done incorrectly (e.g. bad data such as a string when a number's expected, clicking submit multiple times on a web-app, etc...). It's identifying and documenting how to deal with the failures that really take the most effort.

Then assuming a human facing piece of functionality, lead with user interface designs (e.g. wireframes) and written use cases. If this functionality is meant to exist in, or integrate with, another system UML diagrams are useful to show that interaction. At this point, are you hiring a glorified typist or someone who can think? If the former, then really get into the weeds and UML out the class hierarchy.

Templates

Does anyone know where to get sort off a basic use case scenario for an auction site or a site like this one.

my site has to be more off an auction site then a q and answer site.

Basicly, from my ~limited~ understanding, when you start a project, you start with usecases and from there you are going to determine/build an objectmodel.

I would like to hear from someone, that has already got some higher level experience. I would like to see some examples, but advice is ok, also. Maybe, someone can provide some usefull links?

Starting from scratch is ok, but since there are already so many sites alike outthere

Thanks, Richard

In my opinion, use cases are one possible way to get a clear understanding of your requirements. So, as ChrisBD already stated, there won't be a diagram out there that suites your needs and, most importantly, even if it were, this is not desirable.

It's important to know that the valuable part of creating use cases is not the creation of a UML diagram(altough they are helpful for getting an overview of a system). The much more valuable process is writing the textual description of a use case.

There are various templates which guide you through the process (e.g., by Alistair Cockburn [1] or others [2,3] ). If you are interested in the subject, I can recommed the book "Writing Effective Use Cases"[4] by Cockburn.

[1] http://alistair.cockburn.us/Basic+use+case+template (great resources for use case in general)

[2] http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.23.255 (easy for starters)

[3] http://hcid.soi.city.ac.uk/research/Rescue.html (uc embedded in requirements engineering)

[4] http://www.amazon.com/Writing-Effective-Cases-Alistair-Cockburn/dp/0201702258/ref=sr_1_1?s=gateway&ie=UTF8&qid=1285833847&sr=8-1

I am designing a use case diagram for a system that includes a special type of hardware/device that generates multiple events for it self. How do i draw a Use case diagram for those system generated events or how will i proceed with the diagram.

Abdul Khaliq

This is the book on use-cases: http://www.amazon.com/Writing-Effective-Cases-Software-Development/dp/0201702258/ref=sr_1_3?ie=UTF8&s=books&qid=1244456081&sr=8-3.

The drawing part og usecases is not important, it's the textual part thta matters...

I'm trying to define use cases for my project. The problem is I'm not sure how to effectively define a use case, and it looks very messy.

For example like my use case below. I feel like 'View profile', 'View Club' 'View Workshop' is necessary to include because of 'common sense' for user to click on certain profile to view it. So do I really need to define such use cases?

Car Club Use Case

You need to define all the cases necessary to achieve your goal. Generally speaking if there is something important in 'View Workshop' to have it on paper or to pass it to someone - you have to write it.

Ihsan Ramli, while your problem is "I'm not sure how to effectively do %something%" and assuming that you can't give the task to someone else - why not to learn more about it? You can start from couple of widely recommended books, for example Writing Effective Use Cases by Alistair Cockburn.

Sentences like "because... for user to click on certain profile to view it" immediately light a red bulb since use cases represent behaviour requirements and are detached from implementation and design (but can and should refer to them when necessary).

Some comments about your diagram:

  1. 'Create club' (along with 'Delete club', 'Change club name') would look better as a use case one goal level lower and triggered from summary scenario 'Manage club'.
  2. 'Manage workshop' is probably missing for its owner.
  3. Name 'Update item' tells nothing to reader.
  4. 'Join club' would probably look more reasonably triggered from 'View club'.
  5. I don't believe that appointments for workshop and repair have a lot in common to be the same scenario.

Where can I find some free use case scenario templates?

Thanks

PS. I know they're easy to find on google but I asked the question so the best ones could rise to the top.

You might find this book useful:

writing effecitve use case

I need to write a use cases to test the asp.net mvc applicatoin. How can I do that?

Writing Effective Use Cases should demistify use cases for you. Also, check out Asp.Net MVC Test Driven Development and The Art of Unit Testing