On working with Use Cases

UX / User Research
#1

Following up on matrix chat proposing documenting + tracking scenario’s of Forge Federation, and @dachary’s answer on chat.

There are a ton of different ways to document Use Cases and/or Scenario’s. Most important imho is finding a way that those involved feel comfortable with, where amounts of texts are kept to a minimum. Where the result increases common understanding, and the status of the use case implementation can be tracked.

Now what follows is just my input and example text, not necessarily correct or even what you’ll build, just to demonstrate… In use case examples there’s a template they use, and usability.gov uses a similar one.

I imagine that first you start keeping a list. One of actors and one of use cases. They only need a Name and short Description. They are elaborated as needed. Then a use case might look like this:
Name Follow Remote Repository
Description Given my Gitea server finds the Remote Repository, if I Follow it I can now find it via the Explore feature, navigate its entire content and Watch it so I get to see repository activities in my feed.
Primary actor Remote Contributor
Precondition Either of these use cases should succeed:
- Search Remote Repository
- Accept Repository Invitation
Trigger Click ‘Follow’ button on Remote Repositories search result.
Basic flow - Remote Repositories view shows a list of search results
- Each result displays a summary of the Repository Profile
- When clicking ‘Follow’ on a result a confirmation dialog appears
- Accepting the dialog leads to a waiting screen “Retrieving Remote Repository”
- When done loading the UI navigates to the Repository view
- (Remote Repository looks just like a regular one, except for an icon and ‘Remote’ label next to the reop name)
Alternative flows Following alternative flows are documented below:
- Remote Gitea Server Unavailable
- Follow Request Declined

Now interestingly while writing I found an inconsistency while thinking of alternative flows. If a “Follow Request Declined” is possible, then maybe it means that the basic flow is incomplete, or maybe I should split this use case in two to make it clear how a Follow Request is handled.

So this is a bit how I have this in mind. Yeah, it is detailed work. Given your examples of use cases (e.g. this one) I cannot clearly discern the flow and find the edge cases. I see them as more informal descriptions that can be the input to the kind of elaboration above.

1 Like
DRAFT: monthly report, July 2022
#2

Note that, as I interpret it, a User Story is more of a feature perspective, and for this example you get something like:

    As a Remote Contributor,
    I want to be able to Follow a Remote Repository,
    So that I can interact with it from my own Gitea Server as if it were a Local Repository.
#3

A thing I should mention is that I documented the example above at an app-specific perspective. You might also document in a way that is independent of any app / forge, and then the use cases might be part of ForgeFed.

Another possiblity instead or in addtion of such use cases is that you write them out as Gherkin texts (also either generic or app-specific), and then use a Cucumber-like behavior testing tool, to add them to the testsuite of your app. Golang has several good BDD libraries you can use.

#4

Stellar example :heart: I reworked my own use case to use the same format and it is much clearer… I think.

1 Like
#5

One thing you might do to make the documentation chore a bit more bearable is to create a subcategory Use Cases and then assign a template to the new topic creation. In that you can add a pre-cooked use case table and also provide instructions for filling them out as html comments. This will also ensure consistency.

1 Like
#6

Done Use Case category created with template:

image

1 Like