How to Write Good Use Cases

# How to Write Good Use Cases ###### tags: `Use Cases`, `Docs for bc-interns` _We will be asking all intern team members to submit a focal use case by June 15th, focused either on their project or another of their choice. Following is a description of how to write good use cases, drawn from a talk that Joe Andrieu gave to our 2021 interns._ 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.