Per your opening question, here are some use case documents from this community. As you’ve noted there are lots of different levels of detail and formats. Ultimately, it depends on what you want to capture and how it is going to be used.
I’ve found three distinct views useful for describing a complete system (or specification). For the first two, I like to limit scope to one to three pages. For the latter, to no more than a dozen pages if possible.
The first view is a system-wide view where you illustrated the breadth of the system. This is Section 3 User Needs in the Verifiable Credentials Use Case document: https://w3c.github.io/vc-use-cases/
The “single page” has two facets (which ends up as two pages conceptually). The first is the diagram with a simple name of each use case. This, literally, lets you see the entire set of use cases at once. Of course, other use cases are possible; it isn’t meant to be exhaustive. But it does capture a sense of the many different kinds of things you can do with VCs. It’s also designed to give a quick hit of inclusion to potential adopters who see their needs in that view. The second facet of this view is a short paragraph scenario describing the key interactions in each named use case. Together, this should take one to three pages, again, so it is easy to absorb the entirety of the system in on sitting.
The second view that I’m a fan of are focal use cases, as you can see in Section 5 of that same document. It’s also the primary focus of the current DID Use Case document https://w3c-ccg.github.io/did-use-cases.
The idea here is to focus down into the detail of the most impactful use cases. Here you take the time to drill deeper, roughly one to three pages per use case. The key questions are about user motivation, actual interactions with the system, and consequences. In the VC Use Case work, we added sections on trust hierarchy and threat models and it rounded out the focal use cases quite well. The key here is to pick focal use cases that illustrate the capabilities uniquely enabled by the system. In the system-wide view there may be use cases that can be realized with alternate technology, but with the focal use cases, you really want to highlight how this particular technology enables a solution to a problem simply unavailable elsewhere.
The third view is my own Information Lifecycle Engagement Model for deeply describing the entire lifecycle of individuals interacting with a system. Based initially on how CRM systems manage customer lifecycles, this is the approach used for Joram and for Amira, both papers created through RWOT.
The fundamental goal of an Engagement Model is to present the human experience in human readable language. A relatively brief, almost story-like presentation that describes the full scope of necessary interactions with any information system. It uses a strawman technical architecture to ground questions of feasibility, but it is not meant to resolve the design and implementation details. Instead, it’s to help readers get into the head of the main actors, to empathize and understand how such a system would actually be used from before contact through enrollment, use, problems, exit, and re-engagement.
Some general principles for good use cases:
Focus on a single, value generating interactions with the system. Look for illustrative interactions rather than categorical hold-alls: “withdraw cash” rather than “ATM”, “apply for asylum” rather than “refugee”.
Be concrete, using real names and real situations to enable empathy with the primary actors. Readers should be able to place themselves in those roles and evaluate the viability of the use case as if they were the user. And please, please, use names other than “Alice” and “Bob”. Those are so common in security as to be as useless as “A” and “B”. Nobody remembers which Alice you are talking about. Contrast that with the resonant recall of “Joram” and “Amira”. People who have read those papers know immediately the characters and the situation they are in, even years after initial contact.
Focus on human requirements independent of technology as much as possible. Sometimes you need to refer to tech to make a point, but good requirements capture what people need prior to design and implementation decisions. Things like pin codes and keypads presume design choices in the hardware and interface. Avoid when possible.
Separate background, theory, and interaction–and cut out the theory. Often use case authors intermingle the three:
- background context–required to understand user motivations
- interactions–what people actually do, and
- theoretical or ideological reasoning behind the approach.
Separating the background and interaction help clean up the flow, making it easier to see the step-by-step process the system needs to support for a given use case, without losing the context. About theory: use cases are not the place to make ideological arguments or explain the theory behind the system. Or as they say in show business: show don’t tell.
- Keep it short, but not too short. Readers need to be able to understand the nuance of what makes a use case unique, but they also need to be able to absorb it quickly and without a lot of cognitive overhead. The worst outcome of use case gathering is to create a seemingly endless tome of wisdom that is too intimidating and time consuming for people to read. I had one client who considered their 200+ Jira issues as a useful set of requirements. Unfortunately, none of the developers nor the funder agreed. It was just too much to process.
Those are my starter tips for use case development. I’m a fan of natural language and human readable storytelling as the format for capturing use cases. Andrew Hughes @andrewhughes3000 might be able to share his work on identity assurance use cases he’s been collecting for ISO. He has a more meta-data driven approach than I. Both are valid; each highlights different aspects for different audiences.