---
robots: noindex, nofollow
---

# How to Write Good Use Cases
###### tags: `article / in process`

[This article is drawn primarily from Joe Andrieu's talks and commentary about use cases, which we'd like to adopt as general best practice at Blockchain Commons. We'd love to put this out with Joe as the lead author (with whatever edits and changes he likes), to give proper credit to the ideas and procedures.]

Tech Target [defines](https://www.techtarget.com/searchsoftwarequality/definition/use-case#:~:text=A%20use%20case%20is%20a,related%20to%20a%20particular%20goal.) a use case as "a methodology used in system analysis to identify, clarify and organize system requirements. The use case is made up of a set of possible sequences of interactions between systems and users in a particular environment and related to a particular goal." In other words, they're little stories that define what a system needs to do.

Use cases exist because the hard part of programming is not writing the code, but rather knowing what code to write. They help to identify the _right_ code to write, and what code _not_ to write.

One of the problems that we as engineers tend to have when writing use cases is that we often focus on interesting technologies, whether they be blockchain, cryptography, or whatever's coming next year. This can lead to creating solutions that are in search of problems. To develop the most useful (and most used) systems, we need to focus on user requirements, not technical requirements — on real problems and real needs. That's what good use cases can enable.

But, good use cases can to a lot more than that. They allow us to find the boundaries of our system: what they *should* do and what they *won't* do. They allow us to identify risks, threats, and adversaries. Ultimately, they lay a foundation that creates context for discussing a system.

That's why understanding what use cases are and how to write them is a crucial element in system design.

## The Three Types of Use Cases

Before you can write a good use case, you need to know what type of use case you're writing. Broadly, there are three:

**Domain Use Cases.** This is a use case that covers an entire category, such as the "refugee crisis". It's vague and not specific, but it can also reveal a breadth of required uses, as different domains will have different requirements.

**Problem Use Cases.** This is a more specific use cases that reveals a real-world problem and details how someone can use the system to solve the problem. It's the sort of use case that is sometimes omitted by engineers.

**Task Use Cases.** This is another specific use case, but one that focuses on the essential tasks that someone will undertake within a system. It's the sort of use case that engineers often start with.

All three sorts of use cases can be useful. Domain use cases in particular can offer a nice overview. However, when creating requirements for a concrete system, use-case developers will usually be focusing on problems _and_ tasks (and may need to pay special attention to problem if they usually tend to focus on tasks instead).

The [VC Use Cases](https://www.w3.org/TR/vc-use-cases/) document from W3C offers a good example of creating both problem use cases and task use cases — which it calls "user needs" and "user tasks". Its user needs include education, retail, finance, healthcare, professional, legal, and devices needs — each of them a short, specific, and concrete use case. Its user tasks meanwhile include issuing claims, asserting claims, verifying claims, storing claims, moving claims, retrieving claims, and revoking claims. They're very different types of use cases, focused respectively on the user and developer experiences.

## Writing a Use Case

Don't expect to write _a_ use case. Expect to write _a lot_ of use cases. Use cases will often be brief, just a paragraph or so. However, to be optimally useful, they should be precisely written.

Following are best practices and specific steps for writing a use case.

### General Best Practices

Use cases will benefit from the following best practices in conceiving of and writing up your use cases:

**Be Illustrative.** Use cases should be illustrative, not exhaustive. Consider how to demonstrate a system's functionality without trying to lay out every possibility and every variant.

**Be Concrete.** Hand in hand with that, a use case should be concrete. Be extremely specific about what's done by whom in what way. Lay out specific tools and processes that are being used. Don't worry that your specificity is innately ignoring far more possibilities, because again you're trying to be illustrative, not exhaustive. The end result should be a precisely described example of a very specific situation.

**Be Unique.** Avoid including multiple use cases that are essentially the same thing, or even use cases that are slight variations of the same problem or task. The goal is to show the breadth of possibilities that a system must encompass, not every specific detail.

**Be Actionable.** Finally, use cases are only useful if they have actionable results. If a use case addresses problems that aren't solvable or lays out tasks that aren't possible, there's no point in writing it.

### Fourteen Steps for Writing a Use Case

With your general best practices in hand, you're now ready to write a use case. The following steps lay out the big picture of how to do so. Some reiterate the general best practices in a more concrete form.

1. **Identify your use case type.** Before anything else, you need to know if you are writing a problem use or a task use case, as they have different goals and should be approached in different ways.

_Example: identifying a type._ Hannah is writing use cases for a decentralized identity system. Her next one is a problem use case.

#### Planning

When you're planning a use case, you're figuring out what your use case will include.

2. **Reveal a unique capability.** You must decide what unique capability you are going to describe. This should be functionality of the system that is critical (and so is a requirement) and that is sufficiently novel that it's usage isn't obvious.

3. **Focus on a single value-creating transaction.** Lay out the specifics of your use case by determing a single value-creating transaction to highlight. There are three parts to this. First, the transaction should be singular: not multiple transactions, even if they're closely aligned or similar (though variants might supplement a use case). Second, it should create value, not be a pure procedural elemental. For example, logging into a system doesn't innately create value, but doing something (such as updating a credential, revealing a credential, or deleting a credential) after logging in does. Third, the value should be clearly identified.

4. **Avoid technological lock-in.** Don't lock a use case in to technological specifics unless they are entirely crucial to the use case. Generally, a use case should specify a problem or a task and show how to resolve that problem or task, but not the technological structure that underlies that resolution.

5. **Plan to write just enough.** Plan your use case to be brief, unless you decide to make it into a focal use case (see below). Don't worry too much about polish, unless it's something that's going to be published more widely down the road. You have limited audiences, of developers (and possibly users), and you just need to make sure your use case is understandable to them.

_Example: planning a use case._ Hannah decides to write about the problem of accessing the identity system without an authentication token. This allows her to reveal a unique capability: that the identity system can authenticate off of a sung phrase. However, authentication itself isn't a value-creating transaction, so Hannah makes it concrete by revealing how a character can access her car without having any external authentication token. She plans to keep the use case minimal and not to refer to any specific voice-recognition technology.

#### Writing

When you're writing a use case you're following a simple four-step procedure, focusing on characters, motivations, processes, and benefits — the use-case equivalent of beginning, middle, and end.

6. **Incorporate empathizable characters.** A use case is about more than a problem and solution; it's about characters confronting the problem and enjoying the solution. Those characters should be people that the developers and other readers can empathize with, taking actions that they understand for reasons they can agree with.

7. **Know their motivations.** The background of a character is important, as it reveals their reasons for facing a problem (or their needs for accessing a capability). You should know a character's motivations when writing a case study, and you should reference enough of it to make their needs understandable by the reader, but you don't need to write a lot about it — just the bare minimum to set up the problem or task.

8. **Lay out a step-by-step process.** The heart of your use case should be a precise listing of descriptive actions that the character uses to overcome the problem or accomplish the task.

9. **Describe the outcomes.** Finally, a use case should end with a description of the benefits or other outcomes that have resulted from the character following their motivations and engaging in the process.

10. **Identify the new capability.** If possible, identify the unique capability being demonstrated by the use case, preferably as a succinct parenthetical at the end of the use case. This may help you to ensure your use case has a unique capability, and that it's well spotlighted.

_Example: writing a use case._ Hannah writes about a character who likes to swim at the beach, but needs a way to get back into her car afterward without just leaving her keys on the beach. She reveals the step-by-step process whereby the character engages the system by pulling up on the door handle, then singing a snippet from a specific song in order to be authenticated by her car talking to her phone (which is in the glove box). Afterward, her car unlocks and can be powered on by pushing the ignition button. As an added benefit, the character is also fully authenticated to the identity system accessed from her phone, allowing her to immediately begin using other functions, such as playing her favorite playlist on the stereo. She identifies it as "[audible authentication]"

#### Detailing

Though you should now have the complete structure for a use case, some details will help it to shine.

11. **Title your use case.** Make sure your use case has a title that is both descriptive and compelling.

12. **Choose memorable names for your characters.** The characters in your use case should have thoughtful and memorable names as well. Do not under any circumstances go with Alice, Bob, and their compatriots. Instead choose names that people will remember and perhaps even use to refer to the use case.

13. **Define your jargon.** Carefully think about any jargon or products within the use case. Consider whether your entire audience is likely to recognize the jargon, and if not, define it for them. (Or possibly: do away with the jargon.)

14. **Number everything.** If something can be numbered, do so. Especially, number your use cases if you are writing up a number of them. Again, you want to make it easier for people to refer to your use case and its contents.

_Example: detailing a use case._ Hannah chooses "Authenticating after swimming" as the name of her use case and "Coral" as an evocative name for her swimmer. She then erases some early uses of "authenticate" to de-jargonify her use case, which results in a new name: "Unlocking the car after swimming". She eventually numbers it as #7 in her list of use cases for her decentralized identity software.

#### Example: Full Use Case

**Use Case #7: Unlocking the Car after Swimming.** Coral lives several miles from a beach where she swims on her own. She's often angsted about what to do with her electronic key fob for her Kia, which she can't take swimming with her. Her new decentralized identity system can unlock her Kia's smart-key system for her, as long as she leaves her phone running the identity system in her glove box. To activate it, Coral pulls up the door handle and sings out the first two lines of _Kokomo_: "Aruba, Jamaica, ooh, I wanna take ya; Bermuda, Bahama, come on pretty mama". The decentralized identity system matches Coral's voice print against a recording that she'd previously made of the same lines and unlocks her Kia as well as activating it. Any time in the next five minutes, Coral can get in her Kia, sit down, push the ignition, and go. Even better, because she's been recognized by her identity system, she can also begin playing music out of her online music vault. She chooses the Beach Boys, of course. _[audible authentication.]_

## Writing Progressive Use Cases

Use cases can be ordered so that each step shows a progressively more complex (and less naive) situation. For example, a series of three use cases focusing on the need to store backups of private keys could discuss: (1) The output of a bare key; (2) The output of a 2-of-3 set of shares for the key; and (3) The output of a 4-of-9 set of shares for the key, where two out of three keys much be recovered from each of two different groups out of three.

It's crucial when writing a set of progressive use cases to ensure that you're meeting steps #2 and #3 of the process. Each use case must expand upon the prior ones by offering one new unique capability seen as part of a value-creating proposition.

Progressive use cases should usually be distinct, with each one covering a different person and a different scenario, but if there is a valid reason to reveal a storyline for a single character over multiple progressive use cases, it could be useful to do so.

## Writing a Focal Use Case

Though most use cases with be short and succinct, some should get more attention. These are "focal use cases".

You must first identify your focal use cases. This is best done by listing out scenarios (or use cases) and then prioritizing them by importance, for either the developer or the user. What is required? What will appeal? What will sell?

With a prioritized list of 3-5 use cases in hand, the top use cases can then be expanded (or written from scratch in an expanded form, depending on the exact creation process). Each expanded (focual) use case should be several paragraphs long. To preserve the precision and readability of the use case, those paragraphs should be categorized in a standard format.

The [DID Use Cases](https://www.w3.org/TR/did-use-cases/#focalUseCases) and the [VC Use Cases](https://www.w3.org/TR/vc-use-cases/#focal-use-cases) each provide examples of focal use cases. Prime topics include:

* **Background.** What is the foundation that creates the motivation for the use case?
* **Description/Scenario.** What is the step-by-step process for the use case?
* **Challenges.** What problems could potentially rise in the creation or development of the use case?
* **Distinction.** How is this use case unique, and how does it demonstrate a unique capability?

Specific focal use cases may require additional details, such as the [VC Use Cases](https://www.w3.org/TR/vc-use-cases/#focal-use-cases), which carefully list out the Verifiable Credentials referred to in the use case. The most important thing is to make sure that a set of focal use cases remain precise and consistent.

## Conclusion

As engineers, we often approach systems bottom-up, from the solutions. Though that methodology can be vital for describing the tasks incorporated into a system, it's less than half the story. Systems also need to be approached top-down, from the problems. This means listening to the users, solving their problems, and then pairing task-based use cases with problem-based use cases. In fact, the problem-based use cases might lead you to redefine task-based use cases, as you learn what's really needed.

Beyond that, use cases need to be precise and concrete. If you're successful in writing use cases in this form, and if you think about user needs, you'll have a strong foundation for a system, with requirements clearly defined by real needs.

---
---
---

## Outline
1. Intro to use cases
1. What are they?
1. Why are they important?
* Our tendency as engineers is to focus on technologies.
* We want to avoid creating solutions and looking for problems.
* Instead, we want to focus on real problems and needs: user requirements, not technical requirements.
* This allows us to create solutions that will be used.
* Find the boundaries of our system: what it should _and_ shouldn't do.
* It also helps us to assess risks, threats, and adversaries.
* Ultimately: create a medium/context for conversation
1. The Three Types of Use Cases
1. Itemizing the Types
* Domain
* Problem
* Tasks
1. All important
* Domain can give nice overview
* But concrete use cases will tend to focus on problems & tasks
* Engineers tend to focus on tasks, so problems are the ones usually neglected
1. Examples
* [VC Use Cases](https://www.w3.org/TR/vc-use-cases/) has "User Needs" and "User Tasks"
1. Writing a Use Case
1. Expect to write lots of small use cases
1. Know If it's a Problem or a Task
1. General Best Practices
* Be illustrative. (not exhaustive)
* Be unique (Don't have multiple use cases that are fundamentally the same.)
* Be concrete.
* Be describable.
* Be actionable.
1. Twelve Steps to Writing a Use Case
* Planning
1. Reveal a unique capability.
1. Focus on a single value-creating transaction.
* Clearly identify the value!
1. Do not embed specifics technologies
1. Include Characters that are empathizable.
* Writing
1. Know your motivation (but write just enough)
* You have to know the background, but not necessarily write a lot about it
1. Illustrate the steps for creating the value
* Descriptive actions
1. Know your benefits & other outcomes.
1. Write just enough. (Don't polish unless publishing!)
* Detailing
1. Title Your Use Case! (Compelling!)
1. Choose Memorable Names.
1. Number everything.
1. Define your jargon.
1. Writing a Focal Use Case
1. Identify your focal use cases
2. Write more, see [VC Use Cases](https://www.w3.org/TR/vc-use-cases/#focal-use-cases) and [DID Use Cases](https://www.w3.org/TR/did-use-cases/#focalUseCases)
3. Categorize (see examples)
1. Conclusion
1. Listen to the users
2. Solve problems
3. Be precise

-----
## Notes

* Decide Background
* Decide Type (3)

* Short vs Long, the latter being FOCAL USE CASES (See DIDs)
*
[why is this important?]

[we need to focus on user requirements, not just technical requirements]

[need to be able to write *precise* use cases]

-allow us to move on risks, threats, adversaries

we want to avoid creating solutions and look for the problems.

TUTORIAL (JOE): https://lists.w3.org/Archives/Public/public-credentials/2021May/0021.html

COMMENTS (JOE): https://lists.w3.org/Archives/Public/public-credentials/2021May/0021.html

DID USE CASES: https://www.w3.org/TR/did-use-cases/
VC USE CASES (W3C): https://www.w3.org/TR/vc-use-cases/

USE CASES OFFICE HOURS (JOE): https://www.dropbox.com/sh/urq29tdup9kjvt9/AAASTVXo1caclzGVmgNPP2lDa?dl=0

REVISED USE CASE, POST COMMENTS: https://github.com/BlockchainCommons/Community/discussions/45

## Notes from Joe's Office Hours

"The hard part is not writing the code; the hard part is knowing what code to write"

- Requirements Engineering
- How to understand human requirements independent of technology choices

[tactics in response to Use Cases]

### Three Levels of Use Cases

1. Domain
* Category, e.g. "Refuge Crisis"
* Vague, not specific, but still can be useful
* Real breadth of use cases
* Different domains will have different requirements
2. Problem
* Real-world problem
* Describing how someone uses system to solve problem
3. Task
* Given the system
* What are the essential tasks people will need to do?
* Flip-side of Domain
* Coders usually start here

Understand the

Breadth
* Tools that let you see the scope of your application
* All the use cases!

And the

Depth
* Take the problem domain as a map of all the use cases
* Figure multiple domains and categorize uses
* Also figure out what you're not doing
* Creating boundaries, you have to know what your system WILL DO and what it WON'T DO
* THEN you prioritize the "focual use cases — most important

Joe's Best Practices
* Single value-creating transaction [this is lower level than domain]
* e.g., for ATM, it's withdraw money, deposit money, or check balance, NOT enter PIN
* Clear, memorable names [including names in stories, NOT Alice & Bob]
- Title your use case!
- A memorable name can anchor an entire work
* Distinguishes unique capabilities
- Don't have a bunch of use cases that are fundamentally the same
* Describable
* Empathizable
- Stories that connect in a meaningful way
* Actionable

* Keep scenarios, engagement models, and customer journeys **concrete**
- Specificity gives depth
- e.g., Visa, not electronic payment
* Number everything
- Makes it easy to refer to
* Expand & contract
* Just-enough, just-in-time
- requirements should help engineers
- polishing them doesn't necessarily help anyone
* 80/20? Move on

Pragmatic Notes:
* Distinguish background from use case, separate use cases
* Focus on descriptive actions of what people are doing
- with just enough motivation, before (why are they doing this?) AND after (what's the benefit? may be an echo of the first), to anchor why this is a legitimate interaction
* Jargon alert: If you're specific technology, define it, but if not use generic

Some Parallel Notes:
1. Name a unique specific person
2. Identify the specific value that is created by the interaction
3. Illustrated the steps taken to create that value
4. (Bonus) Come up with a compelling title!

==

ARE NOT MEANT TO BE EXHAUSTIVE, THEY ARE MEANT TO BE ILLUSTRATIVE

A lot of requirements engineering is using use cases (and such) AS A MEDIUM FOR CONVERSATION
- listen to what they're trying to do
- map it into our tools
- give it back to them
- they can see what they wanted and what they didn't want

The purpose of use cases is
Not just to capture requirements, but to provide a context for conversation

WE DON'T WANT TO EMBED TECHNOLOGY SOLUTIONS INTO THE STATEMENT OF A PROBLEM.

- We often get *solution statements* rather than *use cases*!