How to write a Use Case

This tutorial explains how to write a use case.

What is a use case?

A use case is a sequence of actions that provide a measurable value to an actor. Another way to look at it is a use case describes a way in which a real-world actor interacts with the system. In a system use case you include high-level implementation decisions. System use cases can be written in both an informal manner and a formal manner. Techniques for identifying use cases are discussed as well as how to remain agile when writing use cases. http://www.agilemodeling.com/artifacts/systemUseCase.htm

A use case describes how an actor uses a system. An actor may not be a person, it could be a banking system, for example.

Use Case Definition

1. One or more scenarios.

2. Self-contained procedure.

3. Independent of other use cases.

4. Starts with the system in a stable state.

5. Ends with the system in a stable state.

6. Identified by the goal of the actor.

7. Contains no time gaps in the flow.

Use Case Benefits

1. Change manual processes into automated processes.

2. Deeper understanding of business processes.

3. Ensure the delivered software works as per the original requirements.

4. Establish an agreement about system requirements.

5. Expose items outside of project scope.

6. Identify alternatives, exceptions, undefined terms, and outstanding issues.

7. Identify gaps between requirements and delivered software.

8. Improve communications between project stakeholder and development team.

9. Prioritize work.

10. Recognize patterns in functional requirements.

Use Case Structure

A use case is comprised of:

1. Actions, Numbers – numbering actions will help readers follow the process flow and, when you are reviewing a use case, help identify a step. Numbering actions improves traceability from requirements to design and testing.

2. Active Voice – it’s important to understand why the active voice is more appropriate than the passive voice when writing use cases. In general, the active voice is more immediate, more confident, and identifies who does what. The passive is fine, and necessary, in different circumstances, for example, if you want to deflect blame from someone. Using the active voice also mean the word count will be reduced, which is important if your use case is very detailed.

3. Alternative Flows – identify branches from the main flow to handle special conditions (i.e. extensions). For each alternative flow, reference the branching step number of the normal flow and the condition which must be true for to execute the extension

4. Alternative Paths – identify the steps to handle variations.

5. Assumptions – identify any assumptions that were made in the analysis that led to accepting this use case into the product description.

6. Attributes – in addition to information such as the actor, direction, and events, you can improve the usefulness of the use case by including project-related attribute information, such as priority, complexity, author, and iteration.

7. Automate use case process – depending on your needs, and the volume of use cases you’ll be creating, you should explore an automation process where you and others can generate use cases on the fly, if necessary. The downside of course if the associated cost, training, and additional overheads. But if you plan to develop use cases on a frequent basis.

8. Brevity – as Shakespeare reminds us, ‘brevity is the soul of wit.’ Brevity in this sense meant intelligence, and this should apply to the title of your process. Keep it short, meaningful, and concise. Actually, see if there is some way to reduce the word count without the title losing any meaning. When we see it like this, rules such as use 2-7 words become meaningless. Use as many as need – but no more.

9. Check, Check again – is it complete? Have you checked that all requirements, business rules, and other specifications are addressed in the use case? Use a traceability matrix to determine (i.e. map) from the requirements document to the use case, otherwise you risk assuming everything has been covered. One suggestion is to use the same ID numbers across both documents, checking them off as you prepare the documents.

10. Colour combination – as well as using clear fonts, when creating images for the use cases, such as process diagrams, use a colour combination with a strong contrast. I know black and white can seem jaded, but if don’t well can look very sharp and powerful. The opposite is backgrounds with dark colours, such as teal, purple, and green, which may have looked trendy at one point but look can look dated and amateur.

11. Consistent – have you ever read a document and found yourself stopping and starting because the tone, phrasing, and terminology keeps changing? This sometimes happens if more than one person is involved in writing the use case. Terms, phrases, and style all change. From a reader’s point of view, it’s distracting. The alternative to this is when words, phrase, style, and even layout are consistent. Strive for this and your readers will thank you.

12. Create a user story – you can help orient the reader by including a brief user story. This should identify who is doing what and why. Keep it specific, brief, and non-ambiguous. The mistake many process writers make is to repeat what’s in the title of the procedure. This adds little or no value. At worse, it adds clutter and wastes the reader’s time. The use case story isn’t required as the use case steps should explain the process. However, most readers are running against the clock. They don’t want to read the entire use case to figure out if this addresses what they were looking for. For this reason, a short user story helps the reader determine if they wish to read the rest of the use case documentation.

13. Diagram – the most useful use cases, from the user’s perspective, include both text and diagrams. They can see at a glance how the process works, and then examine the text to get more granular information. Images, such as process flow diagrams are not mandatory but very helpful. They encourage discussion and allow you to see gaps faster, from m experience, than reading the text. Diagrams don’t need to be works of art. You can create them in PowerPoint or use the yEd graphic editor. One tip – if you create a large diagram, change the page to landscape so it fits better.

14. Events – identify the steps that the actor and system must go through to accomplish a goal. Make sure to identify the flow (i.e. direction).

15. Exceptions – identify errors that may occur during the use case execution, and how the system will respond to those conditions.

16. Exceptions – identify the steps to handle errors and exceptions.

17. Fonts – use a font that is easy to read, renders well on different devices, and doesn’t degrade when converted to PDF. Saying that, I personally try to avoid serif fonts – those like Times Roman with ‘feet’ – as they take took more space that sans serif fonts.

18. Frequency – identify how often will the Use Case will be executed.

19. Identify Goals. A name like Process Invoices doesn’t tell us what’s being done – is it collections, organization, auditing, or some other function? A more insightful name would be Collect Late Payments From Customers. The goal in this example is to collect payments from delinquent customers. The second name does a much better job of defining what the user is trying to do when they perform the use case.

20. Identify specific goals – what we mean here is that you name each use case so that it another person, who is unfamiliar with the document, would know what to expect if they examined it. This means we need to avoid generic and ambiguous titles, such as credit card process, and instead be more specific, for example, credit card application process for new customers. After all, this process may be slightly different than the process for existing customers who are already pre-qualified.

21. Includes – identify other use cases that are included (“called”) by this use case. Common functionality that appears in multiple use cases should be documented in a separate use case.

22. Library – once you’ve created the use cases, I’d suggest you create a dedicated space on the network and upload the files here. If you leave them in MS Word, turn on Track Changes. If you save them to PDF, make sure reviewers have the option to leave comments.

23. Naming convention – one way to achieve this is to create an intuitive naming convention that allows you and other writers to identify High, Medium, and Low use cases. You can also create an Excel spreadsheet to keep track of these, filter the most important, and work on these first.

24. Post-conditions – describe the state of the system after the use case is completed. In other words, now that the process is completed,

25. Pre-conditions – describe the state of the system before the use case starts. This is the baseline of the use case, so to speak. It’s where, for that specific use case scenario, the actor started their respective process. A precondition is one or more criteria which must be true for the use case to start. A precondition represent a type of contract. If the criteria do not exist, the use case can not start. For example, an applicant must be over a specific age to open a bank account.

26. Present Tense – put yourself in the shoes of the person performing the action. Are they in the past, present, or future? In the present, right? They’re performing the action right now. For this reason, write in the present tense. State what occurs here and now.

27. Prioritize – before we start the actual writing of the use cases, identify the most important use cases first, and prioritize these over less critical use cases.

28. Source File – as most everyone has MS Word, it might be best to save the source file in this format. If you save it in another tool, and only have a limited number of licenses, then you may box yourself in as the person responsible for updating the files.

29. Special Requirements – identify additional requirements, such as nonfunctional requirements, performance requirements or other quality attributes.

30. Title – add a sentence long title to the top of the use case.

31. Trigger – identify what initiates the use case. This is the event which causes the use case to start. For example, the bank receive an application form by email.

32. Verbs – it’s common practice to use verbs to describe the process title, but that’s not enough. In addition to using verbs, we need to use the most appropriate verb, the one that brings us as close to the action as possible. So, for example, instead of writing, Create Bank Loan, we can improve it with Validate Bank Loan application. The point here is that in addition to processing a bank loan application, we’re going to validate it.

33. Writing examples – these can help first time writers get started. Provide some sample text, verbiage, and instructions can help novices get started. A suggested format could be as follows: <time or sequence factor>…<actor>…<action>…<constraints> An example may be as follows: At any time after the sales clerk gets the payment, he may update the account.

34. Writing guidelines – it’s recommended to provide some guidelines on how to write use cases. However, there needs to be some flexibility. If your style guidelines are too rigid or formal, your colleagues will spend time (lose time) making sure they adhere to the guidelines instead of focusing on documenting the process. The benefits of an informal style guide cancel out the disadvantages of delays and omissions, which often occurs when people struggle with inflexible guidelines.

What is an Actor?

An actor defines the boundary of the system. The point to note here is boundary.

The components of the system are not actors. For example, a CRM system is not an actor. As the database that stores system information is part of the system, it cannot be an actor.

An actor is:

1. Outside the system being modelled

2. Characterizes a role, a system or some external entity

3. Linked to one or more system use cases

4. A non-overlapping logical grouping of use cases

How to Identify Potential Use Cases

Constantine and Lockwood (1999) suggest that you can identify potential services by asking your stakeholders the following questions from the point of view of the actors:

1. What are users trying to accomplish?

2. What do users need to be able to do?

3. What are the main tasks of users in this role?

4. What information do users need, for example, to create, request, update, or delete something?

5. What information does the system need to give to the user?

How to describe Use Cases

To describe a use case, you need three things:

1. Actor – The actor or actors involved. An actor is a type of user (for example, bank customer) that interacts with the system. The actor is external to the system. Actors don’t have to be people. They can be other systems. For example, the ATM to connect to the customer’s bank. External systems that interact in a use case are also actors.

2. System – The system being used, for example, the ATM. The actor describes a role that users play in relation to the system. Maybe the bank customer is an accountant, but that doesn’t interest us. What interests us is his relationship to the system.

3. Goal – the goal that the actor achieves by using the system. The goal is determined by the actor’s needs.

PS – you can get a good use case template here.

Capturing Use Case Scenarios

Once we understand the actor and the goal for a use case, and have identified key use case scenarios, we can begin some high-level interaction design.

Actors interact with the system by pressing buttons, typing into boxes, clicking on icons and so on to achieve the goal of the use case. A classic mistake made at this early stage of design is to go into technical detail and commit to a specific user interface design or implementation technology.

This is usually the wrong time to make these low-level design decisions.

First, we need to understand what the business logic of the interactions are, then focus on satisfying the business goal of the use case.

An effective way to write use cases is to divide the actions into columns:

1. One for each actor and

2. One for the system.

This lets you see who does what and the order of events in a scenario.

These use case descriptions – one for each key use case scenario – form the basis of high-level object oriented design, the UI design, system test design, user documentation and other useful things we might need later in the development process.

How to Write a Use Case

Write the steps in a use case as follows.

1. Identify who is going to be perform the action, for example, new and existing customers are going to apply for a bank loan.

2. Pick one of those users, for example, new customers.

3. Define what that user wants to do. Each thing she does becomes a use case.

4. For each use case, identify the normal course of events when that user applies for the loan.

5. Describe the basic course in terms of what the user does and how the system responds.

6. Identify alternate courses of events and add those to “extend” the use case.

7. Look for common actions among the use cases. Extract these and note them as common course use cases.

8. Repeat the steps 2 through 7 for all other users.

What else would you add?

Next week we look at how to write technical specifications.

PS – the best book about Writing Effective Use Cases is this one.