Associate each spec with a Use Cases and Requirements document

[csarven]

Each spec should reflect a "Use Cases and Requirements" document.

Edit:
The primary goal of the UCR document is to illustrate the specification scope. An easy-to-understand narrative to describe situations that are applicable to the Solid specifications.

It is not particularly useful (or even meaningful) to have use cases document for each spec in isolation. For starters, we only need one shared UCR document for the whole Solid ecosystem. At a later date, UCR document can be extended or split into multiple documents depending on the classes of products and specification category (as per #138 ).

The UCR document must have Requirements derived from Use Cases. It is good practice to also include User Stories in the same document in which the Use Cases are derived from.

In order to support both the editorial of the UCR document as well as the authoring and editing of the specs in the ecosystem, proposed user stories and use cases should be accompanied with provenance information eg. authors, supporters, implementers, survey, and other documentation. Participants should add +1/+0/0/-0/-1 survey results to each story/case to denote their reasoning along the lines of:

• +1 "yes, I need it, will implement, worth doing"
• +0 "I'm kind of for it, but can live without it"
• 0 "I really don't care about it"
• -0 "I'm kind of against it, but can live with it"
• -1 "out of scope" or "does not belong in first version so we can ship sooner than later" (provide an explanation)

This is not intended to be an exhaustive "how-to". The main point is to share the use cases, be clear about the scope of the specifications, and refer back to the documentation to support the decision process.

[justinwb]

Strongly 👍 to this. We need this both for specific parts (like notifications / real-time updates), but also broadly across solid as a whole. I've started to frame out and document some of this as a vehicle for illustrating the security model, but to @csarven's point - we should look at all of this the same way. The use cases inform and specifically map to items in the specification, as well as to items in the security model. Thoughts on the format used by the verifiable claims group as a template to apply?

[csarven]

There's a lot out there. Consistency is good but we can mix and match to use what's applicable to each spec. Here is a quick dump from my bookmarks:

• https://www.w3.org/TR/ldp-ucr/
• https://www.w3.org/TR/poe-ucr/
• https://www.w3.org/TR/pwp-ucr/
• https://www.w3.org/TR/dpub-annotation-uc/
• https://www.w3.org/TR/shacl-ucr/
• https://www.w3.org/TR/xhtml-rdfa-scenarios/
• https://www.w3.org/TR/dwbp-ucr/
• https://www.w3.org/TR/vocab-data-cube-use-cases/
• https://www.w3.org/wiki/Socialwg/Social_API/User_stories
• https://www.w3.org/2015/spatial/wiki/Working_Use_Cases

See also https://github.com/solid/user-stories to pull things out.

[woutermont]

In solid/user-stories#146 I raised the question whether we should pool the UCR documents together in a single repo/document, based on the discussion during the weekly Solid CG meeting of 2022-12-14. I only now realise it might have been better added to this issue.