March 9, 2007

...Learn TDD with Codemanship

10 Common Use Case Pitfalls

Use cases are by far the most common way of capturing functional requirements that I've come across on my travels as a consultant. I've seen them done a hundred different ways, and I've seen a hundred different pitfalls that use case authors can fall foul of.

It's vitally important to make your use cases - well - usable, so I thought I might highlight my top ten use case gotchas so that maybe some of you folks out there can learn from other people's mistakes.

1. Confusing use case design with UI design

By far the most common trap for inexperienced use case authors is to describe their use cases with UI design details . E.g., "The customer presses the button and the browser displays a pop-up thanking them for their order". The problem with muddling use case flows with UI design details is that it's usually far too early in the design process to be committing to those kinds of decisions. Not only that, but use case authors are not often experienced in UI design, and are arguably not the best people to be making UI design decisions at any point in the development process. Keep your use case documents free of technical detail. Describe the flow of your use cases in purely business terms and leave the UI design decisions for later. E.g. "The sales rep submits their order, and the system confirms it and thanks them for shopping with us".

2. Not having clear business goals for every use case

Does an ATM user have a burning desire to stick a plastic card into a hole in the wall and press some buttons, or do they just want to get some cash? Be absolutely clear of why people want to use the system. If it's not clear from reading the use case what the pay-off for the user is, then you need to ask "why?". If the answer still doesn't make it clear, keep asking "why?" If your questions lead nowhere, then maybe this use case has no value to the user - in which case, it's not worth implementing. Software development is expensive and risky - so be absolutely ruthless about demanding a business justification for every requirement.

3. Confusing use cases with functional areas

Oh boy! How many times have I read 120-page use cases called "Customer Management" or "Billing", with use case scenarios like "Open a new customer account" and "Raise an invoice"? 932,435,765 times. That's how many times. (Well, it seems like 932,435,765 times, anyway...) Inexperienced use case authors have a tendency to get the granularity wrong. "Customer Management" would be a good name for a package containing use cases like "Open a new customer account" and "Send account renewal reminder".

4. Confusing use cases and use case scenarios

Just as prevalent is the mistake of mixing up scenarios and use cases. You might write what you think is a use case called "Submit invoice to customer who has credit terms" and another use case called "Submit invoice to customer who pays on delivery" and model them as subclasses of the use case "Submit invoice". In reality, these are really scenarios of "Submit invoice" and not use cases in their own right. I wrote a blog post a while back that might help you draw a clearer distinction between [use cases and scenarios.

5. Trying to specify all the use cases up front

BIG MISTAKE! No matter how right you think you got the requirements before coding begins, you can bet the farm that as soon as the users see a working system they'll say "ah, now what we really wanted is..." Don't waste your time trying to get the use cases right first time. Agree one or two of the most important use cases with your customer, implement them and get the feedback you'll need to evolve your system design to something more useful. By all means identify what you think all the use cases are, and draw use case diagrams for the system if you wish. Just don't waste your time specifying all the use cases in detail at the start of the project.

6. Specifying use cases in too much detail

If you bring a use case document to me with an appendix and a glossary and an entity-relationship diagram and a screen flow and useful telephone numbers should I have any further questions, I will throw every page away except the one which tells me what the use case is and what the key scenarios are. There's always a danger that paying someone to devote 40 hours of every week to writing use case will result in some very elaborate use case documents. Don't fall into that trap. Pay them extra if they can keep it simple!

This example of a really bad use case model isn't as far-fetched as I'd like to think, sadly

7.Confusing actor names with job titles

The names we choose for actors should reflect the role they play in relation to the system. If the sales manager administers the contact database, then he is playing the role of administrator, not "sales manager".

8. Showing off with your knowledge of use case theory

I rarely have cause to resort to fancy-pants include and extend relationships, let alone use case generalisation. So when I see use case models that scatter them willy-nilly, I get the screaming heebie-jeebies.

9. Failing to make use cases testable

Often I read a use case description, get to the end and have to ask "so what is the outcome of this use case?" To be genuinely useful, use cases need to rad like test scripts (without the test data), making it totally obvious the effect of the use case is on the state of the system.

10. Treating use cases like sacred artifacts

The purpose of use cases is to tell developers what to build and testers what to test and customers what they will get for their money. Once it's built, tested and paid for, arguably they serve as an historical record at most. I've seen way too many projects crippled by the weight of their documentation, trying to keep everything in step with the code. 99 times out of 100, it's not worth it. Spec it, build it, test it and move on.
Posted 13 years, 9 months ago on March 9, 2007