Merge pull request #113 from opt-out-tools/documentation-requirements

Document Usage Scenarios
opt-out-tools · Jun 2, 2020 · 2feca4d · 2feca4d
2 parents 5311fcd + 556057a
commit 2feca4d
Show file tree

Hide file tree

Showing 6 changed files with 72 additions and 0 deletions.
diff --git a/documentation/README.md b/documentation/README.md
@@ -0,0 +1,25 @@
+# Opt Out Documentation
+
+## Usage Scenarios and Requirements
+
+Usage Scenarios are meant to explain click by click interaction. They do reference the exact inputs, and need to be changed when the UI changes. They are organised in to a table that represents the list of tasks that users will go through. There are 3 types of action to help explain the expected behaviour:
+
+- Action - A user interaction
+- Reaction - The way the software reacts to the user action
+- Insight - What the user learns or recognises as a result of their action or the software reaction
+
+There is also a space to link a task to a requirement. This should be done for any requirements listed in the scenario but it's not so important to link to every requirement that's relevant defined in other scenarios.
+
+### Linking to Tests
+
+One place where writing user scenarios comes in handy is that these are the exact things that need to be tested using end 2 end testing. The id of the scenario can be referenced in the test title. Like so:
+
+```
+describe('[US-002] - Hide misogynist tweets, () => {...});
+```
+
+The tasks themselves can be referenced in the test title, like so:
+
+```
+it('[T-01] - Open Extension', () => {...});
+```
diff --git a/documentation/usage_scenarios/001_open_extension_toolbar.md b/documentation/usage_scenarios/001_open_extension_toolbar.md
@@ -0,0 +1,15 @@
+# 001 Open Extension from Toolbar
+
+## Requirements
+
+| ID   | Description                                                         |
+| ---- | ------------------------------------------------------------------- |
+| R-01 | The user can open the extension by clicking the icon in the toolbar |
+
+## Usage Scenario
+
+| Task | Action Type | Description                                                                               | REQ ID |
+| ---- | ----------- | ----------------------------------------------------------------------------------------- | ------ |
+| T-01 | Action      | User clicks Opt Out logo                                                                  | R-01   |
+| T-02 | Reaction    | The extension popup opens                                                                 |        |
+| T-03 | Insight     | The user is aware the popup is open and that they can change the settings with the inputs |        |
diff --git a/documentation/usage_scenarios/002_hide_misogynist_tweets.md b/documentation/usage_scenarios/002_hide_misogynist_tweets.md
@@ -0,0 +1,16 @@
+# 002 Hide Misogynist Tweets
+
+## Requirements
+
+| ID   | Description                                                                       |
+| ---- | --------------------------------------------------------------------------------- |
+| R-01 | Tweets can be hidden or modified in the twitter timeline if they contain misogyny |
+
+## Usage Scenario
+
+| Task | Action Type | Description                                                                             | REQ ID |
+| ---- | ----------- | --------------------------------------------------------------------------------------- | ------ |
+| T-01 | Action      | US-001 - Open extension                                                                 |        |
+| T-02 | Action      | User clicks on slider and drags the input to the "hide all" position                    |        |
+| T-03 | Reaction    | The style of misogynist tweets in the timeline is changed to the selected display style | R-01   |
+| T-04 | Insight     | The user is aware the tweets in the timeline that are hidden were misogynist            |        |
diff --git a/documentation/usage_scenarios/003_show_misogynist_tweets.md b/documentation/usage_scenarios/003_show_misogynist_tweets.md
diff --git a/documentation/usage_scenarios/004_change_display_hidden.md b/documentation/usage_scenarios/004_change_display_hidden.md
@@ -0,0 +1,16 @@
+# 002 Hide Misogynist Tweets
+
+## Requirements
+
+| ID   | Description                                                                       |
+| ---- | --------------------------------------------------------------------------------- |
+| R-01 | Tweets can be hidden or modified in the twitter timeline if they contain misogyny |
+
+## Usage Scenario
+
+| Task | Action Type | Description                                                                             | REQ ID |
+| ---- | ----------- | --------------------------------------------------------------------------------------- | ------ |
+| T-01 | Action      | US-001 - Open extension                                                                 |        |
+| T-02 | Action      | User clicks on slider and drags the input to the "hide all" position                    |        |
+| T-03 | Reaction    | The style of misogynist tweets in the timeline is changed to the selected display style | R-01   |
+| T-04 | Insight     | The user is aware the tweets in the timeline that are hidden were misogynist            |        |
diff --git a/documentation/usage_scenarios/005_go_to_website.md b/documentation/usage_scenarios/005_go_to_website.md