Example user stories to guide our documentation

[gabek]

To guide what specifics we want to document and what problems we want to solve, let's share example user stories to cross reference as we're deciding what specific topics, protocols, recommendations and best practices to share.

From chat:

I have a suggestion. There are a ton of different uses of all of those technologies we talk about. And a ton times ton interop scenarios. We all come at those from a different angles, and none of us see all of them. What about we collect a long list, maybe in the form of user stories, and then see what is needed to accomplish each one of them.

[gabek]

From Johannes

I want to follow Gabe on Mobilizon, so that I am notified in Mastodon when he next time calls for a meeting and I don't miss it.

[Johann150]

It might be interesting to also cover the basics. I think one such basic would be "I want to send a microblog message." which would be pretty common with existing fedi projects, perhaps it should even be specific to a receiving software because different softwares have different requirements.

[jernst]

What about we create one issue per user story? Label them suitably so they can be easily separated from other issues. And then, over time, make sure we have documentation for each one of those user stories.

[aschrijver]

I suggested this in some other places, but Use Cases can be specified in Gherkin language, including scenario's. Which can then be tested in apps, based on e.g. Cucumber or other BDD libs that exist for a particular language.

The Gherkin is a precise definition that could even be part of the Docs, while they form input for the Test Suite(s) at the same time.

Some example (though a very elaborate style of Gherkin scripting) is how DID ORB defines the activitypub.feature.

[jernst]

Use cases are different from user stories.

[aschrijver]

Yes, I deliberately used the term. Gherkin use cases break down into user stories (well, depends on process you wanna follow too, of course)

Update: Copying comments from chat:

Gherkin [describes] expected behaviour. When doing so you create scripts in a language-independent way that can be read almost as "pseudo code" (and - even better - as domain-specific ubiquitous language that non-technical folks might even understand) and where most languages offer libs to automate them as behaviour tests. In follow up to the comment by Johannes Ernst .. Gherkin starts with a use case "As a [stakeholder] I want [feature] so that [this need is fulfilled]", and then follows with scenario's that are more representative of User Stories.

The scenario's can become a big list to cover all the edge cases of a behaviour. Also in Gherkin you can specify input data and preconditions for a use case / scenario, also just in plain text, or markdown-like format.
It forces you to think of consistent terminology, and the language terms you use are candidates to return in the codebase as variable/method names, etc.

Use cases imho offer a more natural fit to highlight "protocol-level capabilities", while user stories are more oriented towards the implementation of those.