Docs: add system use case with retry as alternate flow

[angela-tran]

Closes #1762

The resources that I took a lot of inspiration from are:

• https://guides.visual-paradigm.com/a-comprehensive-guide-to-use-case-modeling
• https://en.wikipedia.org/wiki/Use_case#Examples

From that Wikipedia page, this is what I hope we can get out of writing use cases at this level of granularity:

Better communication

Use cases are often written in natural languages with structured templates. This narrative textual form, understandable by almost everyone, and complemented by visual UML diagrams fosters better and deeper communications among all stakeholders, including customers, end-users, developers, testers, and managers. Better communications result in quality requirements and thus quality systems delivered.

Quality requirements by structured exploration

One of the most powerful things about use cases resides in the formats of the use case templates, especially the main success scenario (basic flow) and the extension scenario fragments (extensions, exceptional and alternative flows). Analyzing a use case step by step from preconditions to postconditions, exploring and investigating every action step of the use case flows, from basic to extensions, to identify those tricky, normally hidden and ignored, seemingly trivial but realistically often costly requirements... is a structured and beneficial way to get clear, stable and quality requirements systematically.

Minimizing and optimizing the action steps of a use case to achieve the user goal also contribute to a better interaction design and user experience of the system.

Facilitate testing and user documentation

With content based upon an action or event flow structure, a model of well-written use cases also serves as excellent groundwork and valuable guidelines for the design of test cases and user manuals of the system or product, which is an effort-worthy investment up-front. There are obvious connections between the flow paths of a use case and its test cases. Deriving functional test cases from a use case through its scenarios (running instances of a use case) is straightforward.

[github-actions]

Coverage report

The coverage rate went from 90.87% to 90.87% ➡️
The branch rate is 85%.

None of the new lines are part of the tested code. Therefore, there is no coverage data about them.

[angela-tran]

Here's a screenshot of the page in my docs site running locally:

[machikoyasuda]

Does 3b1 mean the user clicks the X on their browser, or that there is a button that takes them to Home or somewhere else? (Or is this kind of more specific user interface question not what a Use Case is all about? Not sure).

[angela-tran]

Yeah, so 3b1 is saying that the user's only alternative to retrying is to give up. And right, for use case purposes, we are not concerned with what specific UI mechanism they use to give up. The focus is on how the system and the user respond to each other.

Here I'm documenting how the app currently works, but if let's say we wanted different behavior, we could update these alternate flows, e.g. we could add 3c1. Transit rider chooses to start over completely or 3d1. Transit rider contacts customer support or whatever we think would be the best user experience. The nice thing about this is it expresses what the change is at a basic, conceptual level for everyone to see without having to touch Figma or code.

Side note: I'm not sure if it's actually necessary to document Transit rider leaves the Benefits app -- that's a thing that really can happen at any point for any use case, right? -- but I left it in here for this first round to spark questions just like yours.

[machikoyasuda]

3a1 means that the user has to have a Button to retry right? Or be allowed to use the Back button Browser?

[angela-tran]

Yeah, 3a1 means that the app needs to provide the user with some way to go back to initiate the enrollment process. In the current implementation, this is manifested as a button that takes the user back to /enrollment.

As for the question about the browser back button, I would guess that since our app has a "Previous page" button on some pages, this implies that our UX philosophy is to not solely rely on the browser's back button.

[angela-tran]

@thekaveman @machikoyasuda @indexing What do y'all think about scheduling some time to go over this format and terminology? Maybe next week or after the break? Despite there being so much literature on use cases, I found that there is a lot of variation on how people actually write them, and it took a bit for me to have a clear idea on what different parts of it mean to me.

[thekaveman]

@angela-tran we have a workshop next Wed, is that waiting too long or would that work for a discussion?

[angela-tran]

@thekaveman Next Wednesday's workshop sounds great! Thanks

[thekaveman]

Looking really good!

[thekaveman]

This is a great start!

I think we talked yesterday about renaming the current "Use Cases" section into "User Flows" or something? In the next iteration of this work I'd like each of these newer "system use cases" to be their own page/doc in a folder -- so we get the free nav menu and easier linking etc.

[machikoyasuda]

Tasks discussed yesterday:

• Rename the current "Use Cases" to "Enrollment Pathways". Then remove the term "Enrollment Pathway" from the Veteran subtitle.
• Remove College Discount entirely.
• Andy to rewrite Older Adults (renamed from Seniors) to the same format as the Veteran's one.