Skip to content

Commit

Permalink
User Stories - Test PR (#306)
Browse files Browse the repository at this point in the history 
* User Stories - Test PR

- Proposed restructuring of requirements section to include Use Case Categories and User Stories
- Uses two example user stories from TD TF, as discussed.
- Old material is retained, for now.  We need to land pending PRs to bring it up to date, then  reorganize into user stories.

* Update index.html

* reorganized based on discussion

* use subsections for use case categories

* minor fixes and HTML repairs

=> Going to merge for now, after discussion in Usecases call Nov 20, but there is more restructuring to do with the rest of the requirements section.
  • Loading branch information
@mmccool
mmccool authored Nov 20, 2024
1 parent 451fc5a commit 04767d9
Showing 1 changed file with 153 additions and 82 deletions.
235 changes: 153 additions & 82 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8576,15 +8576,167 @@ <h2>Edge Computing</h2>
</dl>
</section>

</section> <!-- horizontal-ucs -->
<!-- CATEGORIES -->

</section>
<section id="sec-use-case-categories">
<h1>Use Case Categories</h1>
<p>The following categories group Use Cases that share a common property.
In the definition of a User Story, use case categories can be cited as
motivations rather than (or in addition to) specific use cases.</p>


<section id="CAT-Security-Public-Service">
<h2>Security Public Service</h2>
<p>Provides a public service. Misuse can result in lack of support to other users.</p>
<ul>
<li>
Supporting Use Cases:
<ul>
<li>
[[[#UC-interactive-public-spaces-1]]]
</li>
<li>
[[[#UC-edge-computing-1]]]
</li>
<li>
[[[#UC-ar-virtual-guide-1]]]
</li>
</ul>
</li>
</ul>
</section>

<section id="CAT-Security-Private-Information">
<h2>Security Private Information</h2>
<p>Handles personal or confidential information. Misuse could disclose privately identifiable information (PII) or sensitive business information.</p>
<ul>
<li>
Supporting Use Cases:
<ul>
<li>
[[[#UC-interactive-public-spaces-1]]]
</li>
<li>
[[[#UC-edge-computing-1]]]
</li>
<li>
[[[#UC-ar-virtual-guide-1]]]
</li>
</ul>
</li>
</ul>
</section>
<section id="CAT-Security-Safety-Critical">
<h2>Security Safety Critical</h2>
<p>Misuse has the potential to cause personal injury.</p>
<ul>
<li>
Supporting Use Cases:
<ul>
<li>
[[[#UC-interactive-public-spaces-1]]]
</li>
<li>
[[[#UC-edge-computing-1]]]
</li>
<li>
[[[#UC-ar-virtual-guide-1]]]
</li>
</ul>
</li>
</ul>
</section>
<section id="CAT-Security-Business-Critical">
<h2>Security Business Critical</h2>
<p>Misuse has the potential to cause financial injury or damage to business operations or reputation.</p>
<ul>
<li>
Supporting Use Cases:
<ul>
<li>
[[[#UC-interactive-public-spaces-1]]]
</li>
<li>
[[[#UC-edge-computing-1]]]
</li>
<li>
[[[#UC-ar-virtual-guide-1]]]
</li>
</ul>
</li>
</ul>
</section>
<section id="CAT-TD-Creation-Simplification">
<h2>TD Creation Simplification</h2>
<p>Simplifying the process of TD construction is helpful to ease the task of TD writers and generators.</p>
<ul>
<li>
Supporting Use Cases: All.
</li>
</ul>
</section>
</section>

<!-- REQUIREMENTS -->

<section id="requirements">
<h1>Requirements</h1>

<section id="sec-user-stories">
<h2>User Stories</h2>
<p>User stories provide a high-level summary of a requirement in the form of
a single sentence that describes a stakeholder (Who has the need),
a technical requirement (What they need; a capability or condition; features),
and a functional requirement (Why they need it; the purpose or motivation; use cases).
These are often stated in the form of a sentence: "As a <em>Who</em> I need <em>What</em> so that I can <em>Why</em>."
For clarity, the following user stories break out each part in a list.
Each user story will in addition identify one or more Use Case (or Use Case Categories)
that establishes the motivation for the identified capability.
Capabilities correspond to sets of features in other technical specifications.
</p>
<p class="ednote">Define how user stories and features are linked. We can link back from
implemented features to user stories, but want to avoid unstable links e.g. to documents
maintained in github. If we have bidirectional links we need some mechanism to keep them
consistent.</p>
<section id="US-connection-oriented-protocols">
<h3>Connection Oriented Protocols</h3>
<dl><dt>Who (As a...):</dt><dd>Deployer of devices with connection oriented protocols.</dd>
<dt>What (I need...):</dt><dd><p>Reusable Connection descriptions in a TD.</p>
<dl>
<dt>Details:</dt><dd>For protocols that are based on an initial connection and then subsequent messages,
a Consumer can reuse the initial connection rather than opening a new connection each time.</dd>
</dl>
<dt>Why (so that I can...):</dt><dd><p>Better describe connection oriented protocols such as MQTT and WebSockets.</p>
<dl>
<dt>Motivating Use Case:</dt><dd><a href="#UC-open-field-agriculture-1">Open Field Agriculture</a></dd>
</dl>
</dd>
</dl>
</p>
</section>
<section id="US-reusable-defaults-per-TD">
<h3>Reusable Defaults per TD</h3>
<dl><dt>Who (As a...):</dt><dd>Designer/Developer of TDs</dd>
<dt>What (I need...):</dt><dd>Reusable Connection descriptions in a TD</dd>
<dt>Why (so that I can...):</dt><dd><p>Simplify TDs in cases without usage of default terms or to avoid redundancy</p>
<dl>
<dt>Motivating Use Case Category:</dt><dd><p><a href="#CAT-TD-Creation-Simplification">TD Creation Simplification</a>.</p>
<dt>Details:</dt><dd><p>There are at least three sub-problems that motivate this feature:</p>
<ol><li>If the media type is common across forms but is not `application/json`, it otherwise needs to be repeated in each form.</li>
<li>If there are common protocol stack configurations such as different default verbs, baud rates, and endianness, they otherwise need to be repeated in each form.</li>
<li>Multiple bases are not otherwise possible, so each form repeats multiple bases. This is relevant (for example) when a TD has both local and public IP addresses.</li>
</ol>
</dd>
</dl>
</dd>
</dl>
</section>
</section>

<section id="sec-functional-requirement">
<h2>Functional Requirements</h2>
<p class="ednote">We will keep this and following subsection for now but should consider reorganizing them into user stories.</p>
<p>This section defines the properties required in an
abstract Web of Things (WoT) architecture.</p>

Expand Down Expand Up @@ -8917,87 +9069,6 @@ <h3>Security</h3>
mechanism commonly used in the web, such as Basic,
Digest, Bearer and OAuth2.0.</p>
-->
<section>
<h4>Use Case Categories</h4>
<dl>
<dt id="CAT-Security-Public-Service">Security Public Service</dt><dd>
<p>Provides a public service; misuse can result in lack of support to other users.</p>
<ul>
<li>
Supporting Use Cases:
<ul>
<li>
[[[#UC-interactive-public-spaces-1]]]
</li>
<li>
[[[#UC-edge-computing-1]]]
</li>
<li>
[[[#UC-ar-virtual-guide-1]]]
</li>
</ul>
</li>
</ul>
</dd>
<dt id="CAT-Security-Private-Information">Security Private Information</dt><dd>
<p>Handles personal or confidential information. Misuse could disclose privately identifiable information (PII) or sensitive business information.</p>
<ul>
<li>
Supporting Use Cases:
<ul>
<li>
[[[#UC-interactive-public-spaces-1]]]
</li>
<li>
[[[#UC-edge-computing-1]]]
</li>
<li>
[[[#UC-ar-virtual-guide-1]]]
</li>
</ul>
</li>
</ul>
</dd>
<dt id="CAT-Security-Safety-Critical">Security Safety Critical</dt><dd>
<p>Misuse has the potential to cause personal injury.</p>
<ul>
<li>
Supporting Use Cases:
<ul>
<li>
[[[#UC-interactive-public-spaces-1]]]
</li>
<li>
[[[#UC-edge-computing-1]]]
</li>
<li>
[[[#UC-ar-virtual-guide-1]]]
</li>
</ul>
</li>
</ul>
</dd>
<dt id="CAT-Security-Business-Critical">Security Business Critical</dt><dd>
Misuse has the potential to cause financial injury or damage to business operations or reputation.</p>
<ul>
<li>
Supporting Use Cases:
<ul>
<li>
[[[#UC-interactive-public-spaces-1]]]
</li>
<li>
[[[#UC-edge-computing-1]]]
</li>
<li>
[[[#UC-ar-virtual-guide-1]]]
</li>
</ul>
</li>
</ul>
</dd>
</dl>
</section>
<section>
<h4>Risks</h4>
<p>Risks are defined in detail in the Security and Privacy Guidelines document.
Expand Down

0 comments on commit 04767d9

Please sign in to comment.