User Story relation to the Use Case

[egekorkan]

In the TD call, we discussed that it would be good to explain why a user story is linked to a use case. So the user story submission template should contain some instructions on this.

[benfrancis]

What is the reason for having both use cases and user stories? This seems to be different to the WoT Use Cases & Requirements document used for the 1.x family of specifications.

I understand that use cases and user stories are different tools with different purposes, but I would usually expect to see one or the other but not both. What is the experience of other people on this?

My understanding of use cases is that they originate from traditional software development in the 1980s (leading up to the invention of UML) and are very detailed and structured written requirements containing information like:

• ID
• Title
• Primary Actor
• Description
• Trigger
• Preconditions
• Postconditions
• Exceptions
• ...

(Though this is not what the current use case template in this repo looks like)

User stories come from more modern agile software development methodologies and are intended to be much more concise, with the goal of shifting the focus from writing about requirements to talking about them. The user story itself is usually written as a single sentence with a particular structure "As a < type of user >, I want < some goal > so that < some reason >", but is only intended as a conversation starter. User stories usually have three components:

• Card (containing the user story sentence)
• Conversation (the discussion around the requirement)
• Confirmation (a set of acceptance criteria to test when the requirement has been met)

(Though again, this is not quite what the current template in this repo looks like)

I find the current templates a bit strange because they are not quite what I would recognise as use cases and user stories.

I don't think the relationship is as simple as use cases being broken down into user stories, which appears to be the current interpretation in the Thing Description task force. If anything it could be the other way around.

However, I'm not convinced that we need use cases and user stories and requirements...

---

As an example of an alternative approach, in the Web Thing Protocol Use Cases & Requirements requirement we have a set of high level user stories (technically incorrectly referred to as use cases) which explain the motivations for needing the specification, and then a derived set of granular functional requirements for what the specification should define. See the examples below...

User Stories

• As the manufacturer of a smart building hub for commercial buildings, I want to bridge a wide range of different building management systems to a single standardised interface that my smart building software can consume.
• As a facilities manager of a commercial building I want to consolidate my multi-vendor building management system into a single standardised interface that I can use for command, control, automation and analytics for my building.
• As the developer of a cloud service which provides digital twins of commercial buildings, I want to be able to consume data from a wide range of devices and building management systems in order to maximise the size of the market for my service.
• As a facilities manager of a commercial building, I want to have a choice of third party services which can provide analytics for the data from my building management system so that I am not locked into a single service provider and can find the best value service for my needs.
• As a facilities manager of a commercial building I want to monitor and control the HVAC, lighting, safety and security systems of my building all through a single desktop or tablet application, so that I don't have to piece together information from multiple separate systems in order to get a full picture of the operations of my building.

Requirements

• MUST define a way for a WoT Consumer to request a reading of the current value of a property of a Web Thing
• MUST define a way for a WoT Consumer to write the value of a property of a Web Thing
• MUST define a way for a WoT Consumer to invoke an action on a Web Thing
• MUST define a way for a WoT Consumer to subscribe to an event on a Web Thing so that it gets notified whenever an event is emitted

I'm not necessarily saying that all the WoT specifications should follow this approach, just that this is one approach for getting from high level user stories to granular requirements without using use cases (in the traditional sense) at all.

[egekorkan]

Some notes about past and present:

• There have been way too many discussions about this whole process. It is normal (at this point) that it is confusing in the first look.
• In the past, use cases (as published) were some generic "text" about IoT use cases. Thus, they did not help to drive specs.
• We need to point to where spec features come from when we go for REC. This is a W3C requirement. "Where" can be a set of issues, use cases, user stories, requirements, whatever. It should be clear for the W3C that we do not invent stuff out of thin air. A Use Cases and Requirements document is thus not a requirement.
• In the past, there were PRs coming to TD repo, adding features (terms) without any explanation why.
• Use Cases document and Architecture document have overlaps. Also, they are both useful when we want to give some high-level material to "managers"
• The way one feature is prioritized in a spec over the other is not exactly defined.
• See https://github.com/w3c/wot-thing-description/tree/main/proposals/project-management and https://github.com/orgs/w3c/projects/80 .
• We want to link back (ideally in spec text) to a stable link explaining where the feature came from.
• The current user story template is in the same spirit as what you have put above ("As a < type of user >, I want < some goal > so that < some reason >"). It is just broken down into multiple fields. Acceptance criteria is something we can add.

With those in mind, I simply want to see very specific "text" about a new feature someone wants to see in a spec. We call these user stories atm. You have called them requirements. I am fine with both.

Use cases are not necessarily broken down to user stories. Use cases are just some high level motivations to use a WoT spec. The need to set polling interval is very technical, we want to understand why you want to do that in the first place (this is a simple example, I think).

[benfrancis]

@egekorkan wrote:

We call these user stories atm. You have called them requirements. I am fine with both.

Ah, so the user stories are intended to be the "requirements" part of "use cases & requirements", not the "use cases" part? That wasn't clear to me.

I don't have any problem with expressing requirements as user stories if that's the intention.

[chachamimm]

We had not properly discussed the definition of User Srories. In the future we should discuss the definition. If possible, I would like @benfrancis to join us.

However, we are using the term User Stories as one of the Requirements to improve the issues mentioned in @egekorkan comment.