justinwb
commented
5 years ago 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
woutermont
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 https://github.com/solid/specification/issues/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:
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.