Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: add system use case with retry as alternate flow #1798

Merged
merged 3 commits into from
Dec 14, 2023

Conversation

angela-tran
Copy link
Member

@angela-tran angela-tran commented Nov 29, 2023

Closes #1762

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

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.

@angela-tran angela-tran self-assigned this Nov 29, 2023
@github-actions github-actions bot added the documentation [auto] Improvements or additions to documentation label Nov 29, 2023
Copy link

github-actions bot commented Nov 29, 2023

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 angela-tran force-pushed the docs/system-use-case-enrollment branch from 4e6c28e to 6c9149b Compare November 29, 2023 00:01
@angela-tran
Copy link
Member Author

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


- 3a. Payment processor returns with one of the following errors: address verification failed, token is invalid, or general server error
- 3a1. Transit rider chooses to retry, starting back at initiating the enrollment process
- 3b1. Transit rider leaves the Benefits app
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member Author

@angela-tran angela-tran Nov 30, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

**Alternate flows**:

- 3a. Payment processor returns with one of the following errors: address verification failed, token is invalid, or general server error
- 3a1. Transit rider chooses to retry, starting back at initiating the enrollment process
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

@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
Copy link
Member

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

@angela-tran
Copy link
Member Author

@thekaveman Next Wednesday's workshop sounds great! Thanks

Copy link
Member

@thekaveman thekaveman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking really good!

docs/use-cases/system-use-cases.md Outdated Show resolved Hide resolved
docs/use-cases/system-use-cases.md Outdated Show resolved Hide resolved
docs/use-cases/system-use-cases.md Outdated Show resolved Hide resolved
@angela-tran angela-tran force-pushed the docs/system-use-case-enrollment branch from 90be6de to 1f3d8c3 Compare December 7, 2023 15:27
@angela-tran angela-tran marked this pull request as ready for review December 7, 2023 15:28
@angela-tran angela-tran requested a review from a team as a code owner December 7, 2023 15:28
Copy link
Member

@thekaveman thekaveman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

machikoyasuda commented Dec 7, 2023

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.

@angela-tran angela-tran merged commit 0e252b2 into dev Dec 14, 2023
8 checks passed
@angela-tran angela-tran deleted the docs/system-use-case-enrollment branch December 14, 2023 21:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation [auto] Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Write small use-case for "enrollment retry" button
3 participants