[Discuss] Focus on Functional Requirements

[mmccool]

Propose that the UC&R document focus on functional requirements (what needs to be accomplished) not technical requirements (how something should be accomplished). Technical requirements can be stated in each deliverable.

To discuss; please add comments below.

[egekorkan]

I sort of agree, we should definitely write a definition for the different types of requirements and give an example. However, a functional requirement should still touch WoT and be technical enough. For example, "I want to collect data from IoT sensors and display on a dashboard" has no technical enough requirement for me.

[chachamimm]

I agree with @egekorkan.

I think it is important to clarify the scope of UseCases TF that must be considered.

And I think we should clarify the difference between functional requirements and technical requirements.

[k-toumura]

How about classifying the use cases as follows and discussing them with different templates in different session or task forces?

1. Use cases to guide what should be standardized:
   • Including specific user stories: these should allow us to understand situation where TD is used, what to describe in it, etc.
   • It enables us to identify functions that are currently lacking in TD, discovery, etc. (= gap analysis)
2. Use cases to explain the applicability of WoT:
   • Clearly explain the benefit of using WoT to those outside the WoT WG, Chapter 4 and 5 of the current Architecture document may correspond to this. (the architecture TF might be a suitable candidate to collect and discuss them)
3. Case studies from implementing IoT solution using WoT:
   • Introduce the experiences of using WoT in specific projects. (the marketing TF or CG might be suitable to collect and discuss them)

[egekorkan]

@k-toumura I really like your proposal. Since you have already hinted, we can even call them separately: use cases or user stories, application scenarios and case studies, respectively.
As the WoT CG co-chair, we have been already collecting case studies where people present them in a meetup or talk about it in the Discord server. We just never gave them a name. Marketing TF can be then tasked to disseminate such information.

[mmccool]

The proposal to classify use cases into different categories is useful, but not addressing the "functional/technical" requirements distinction for this issue. Move suggestion to another issue?

[chachamimm]

I think there are several categories of Use Cases. I think the focus of Use Cases is "1" of @k-toumura comment. The "2" of @k-toumura comment is diagrams used to explain features on each documents. And The "3" is diagrams to explain WoT for implementation report.

And I think we should clarify what "functional requirements" is and what technical requirements is. But I think "functional/technical" requirements should be based on the Use Cases documents.

[egekorkan]

And The "3" is diagrams to explain WoT for implementation report.

Even though that would be correct in general, our implementations reports are much more detailed than that. In the future, we can actually use such descriptions in addition to the data we currently have in the implementation reports.

In any case, it is a good proposal and we can hit two birds with one stone :)

[mmccool]

Regarding the original question, my impression of the above is that it's reasonable to focus on functional requirements in the UC&R document, as long as they are detailed enough to extract technical requirements and motivate features in other documents.

I think the category discussion should be moved to another issue.

[mmccool]

As for some examples, here is one we discussed:
Functional requirement: Things need to provide access controls to restrict access to specific users.
Techical requirements: Things should be able to support OAuth2.

[mmccool]

Another one:
Functional: Things should be able to notify subscribers in a timely way of events.
Technical: Things should support SSE. (and X, Y, Z, other event notification mechanisms in other technical requirements)

In these examples, note that both OAuth2 and SSE are HTTP-specific, so really belong in the HTTP Binding. Each protocol may have its own way of doing these things. So it would be better IMO to discuss these detailed technical requirements in the TF working on the HTTP binding (for example). That means there is additional technical requirement definition work needed in the TF. However these can be related back to a functional requirement.

[egekorkan]

Just to comment on the examples above from @mmccool. I have mentioned similar comments in the meeting but only for the first one. Here they are in one place:

• In the OAuth2 example: Why is the technical requirement OAuth2? I can do the same by maintaining a list of username passwords. A requirement for OAuth2 should mention offloading the authentication to another party.
• In the SSE example: Any solution that supports eventing would satisfy the functional requirement. The Use Cases TF should extract the technical requirement and give it to the corresponding TF. If the Use Case needs DDS, the work of the Binding TF is to create a DDS binding in the first place. The Binding TF cannot know on its own that the Use Case needs DDS if it is not written there in the first place.