RFC Organise feature specifications

[djbusstop]

This is a Request for Comment (RFC) regarding how we write and organise specifications regarding the expected behaviour of the web extension. I will use the word "requirement" to mean documentation of a feature. Requirements should attempt to explain in as much detail as possible the actions, reactions, and outcomes of how the software is used.

Requirments would be written in conjunction with usage scenarios. These use scenarios explain how the requirments are turned in to actions. See more in the Content section of this RFC. This process of writing requirements and usage scenarios is not required for every issue but it would be required for every issue that adds or changes the interaction of the extension. Usually this means that if it requires UX or UI changes, it will need a new or updated requirement. Considering the UX doesn't have too many features this is not actually too much work, and will be helpful with scaling. Below I will explain how these would work and some of the benefits of using this structure with how it relates to testing and development process.

Location

All requirments and usage scenarios would be kept in a directory called documentation/ which exists in the top level of the repo. Here are the contents of the documentation repo:

├── README.md
└── user_scenarios
    ├── 001_open_extension_toolbar.md
    ├── 002_hide_misogynist_tweets.md
   ...
    └── 005_link_to_website.md

Naming

I propose to use numbered IDs that increment when a new feature is needed. A small bit of text should follow the number ID to make it easier to identify which scenario is related to which feature

Content

Usage senarios are markdown files that follow a template. The content includes requirements in a table at the top and a usage scenario also represented as a table below. There should only be one use scenario per file. When a new usage scenario is needed, a new file should be created. A usage scenario can reference another usage scenario as a task. Or it can reference another requirement from any other usage scenario file. Below is a simple example.

# 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 |        |

Requirements

Requirements are meant to be generic. They are less likely to change when changing the UI or UX. They are given an ID that starts from 01 on each usage scenario file. To reference them from another file, use this structure [US-001 R-01]

Usage Scenario

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', () => {...});

Action points

• Create documentation directory
• Write readme for documentation using some information from this RFC.
• Create documentation for all existing requirements and usage scenarios(there's not much)

Questions

How are requirements and usage scenarios different from user facing documentation?
Answer: The requirements and usage scenarios are quite fine grained and show how everything works. Maybe it helps some users to understand but it's not necessarily meant as an operation guide, but it's meant as a reference for the expected behaviour and specification of interaction.

[djbusstop]

Include a precondition section on usage scenario

[ribicn-softerrific]

Seems fine. For tests, we can just copy/ paste the description from tests to readme file

[lucie-docs]

Sounds good to me!