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.

Sign up for GitHub

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
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6c9149b
docs: add system use case with retry as alternate flow
angela-tran Nov 28, 2023
6fcb1c4
fix: update docs and comments to remove outdated information
angela-tran Dec 7, 2023
1f3d8c3
chore: use 'phase' instead for better understanding across the team
angela-tran Dec 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions benefits/enrollment/templates/enrollment/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ <h1 class="pb-lg-8 pb-4">
},
onTokenize: function (response) {
/* This function executes when the
/* card/address verification returns
/* card verification returns
/* successfully with a token from enrollment server */
amplitude.getInstance().logEvent(closedEvent, {status: "success"});

Expand All @@ -67,7 +67,7 @@ <h1 class="pb-lg-8 pb-4">
},
onVerificationFailure: function (response) {
/* This function executes when the
/* card/address verification fails and server
/* card verification fails and server
/* return verification failure message */
amplitude.getInstance().logEvent(closedEvent, {status: "fail"});

Expand Down
31 changes: 31 additions & 0 deletions docs/use-cases/system-use-cases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
The use cases documented on this page focus on how the system is supposed to work from the perspective of the end user.

### Use case: Enroll contactless card to receive transit benefit

**Primary Actor**: Transit rider

**Systems**: Benefits app, payment processor

**Preconditions**:

- Transit rider has confirmed their eligibility with the Benefits app
- Transit rider has their contactless card information available
- Benefits app is able to contact the payment processor

**Trigger**: Transit rider initiates the enrollment phase

**Basic flow**:

1. Transit rider enters their contactless card information
2. Benefits app passes that information to the payment processor to enroll the card
3. Payment processor successfully enrolls card

**Alternate flows**:

- 3a. Payment processor returns with one of the following errors: card verification failed, token is invalid, or general server error
- 3a1. Transit rider chooses to retry, starting back at initiating the enrollment phase
- 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 •
edited
Loading

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.


**Postconditions**:

- Transit rider's contactless card is enrolled to receive the transit benefit
Loading