Merge pull request #176 from arc42/#167-requirements-pattern

#167 requirements pattern

_articles/06-quality-requirements.md

@@ -27,19 +27,38 @@ Quality scenarios, in short, are a pragmatic, easy-to-use and general approach t
 >You find {{ requirement_posts | size }} examples of such quality requirements on this site (see [examples](/requirements)).
 
 
-### General structure of quality scenarios
+### General structure of quality scenarios (SEI-version)
 
 ![general form of quality scenarios](/images/articles/q-requirements/q-scenario.png){:width="50%"}
 
 
 * **Event/stimulus**: Any condition or event arriving at the system.
-* **Response**: The activity undertaken after the arrival of the stimulus.
-* **System** (or part of the system): Some artifact is stimulated, which may be the whole system or some distinct pieces (artifacts) of it.
+* **Source of stimulus**: The entity (person, system, or other actor) that generates the stimulus.
+* **Environment**:The conditions or context under which the stimulus occurs.
+* **Artifact**: The part of the system that is affected by the stimulus.
+* **Response**: How the system should react to the stimulus. The activity undertaken after the arrival of the stimulus.
 * **Metric** (response measure): The response should be measurable in some fashion, so that this scenario (quality requirement) can be objectively assessed or tested.
 
+Although this template is widely used, it suffers from some drawbacks:
 
+* The template's detailed nature can make it time-consuming to complete, especially for numerous scenarios.
+* Teams might feel compelled to fill out all sections in detail, even when not necessary for every scenario.
+* The comprehensive approach might not align well with fast-paced, agile development methodologies.
 
+In practice, a slightly reduced template proved to be sufficient, let's call it the Q42-Requirements template:
 
+### Pragmatical Quality Scenario
+
+**Context/Background**: A brief description of the situation. This includes the type of system, the relevant environment or operational setting, and the specific condition being considered.
+
+**Source**: The origin of the event or stimulus that triggers the scenario. This could be a stakeholder action (e.g., user interaction, administrator action) or an external event (e.g., system load, security threat, API call).
+
+**Metric/Acceptance Criteria**: A clear, measurable outcome that determines whether the system meets the desired quality attribute. This could be expressed as a specific performance metric, threshold, or success criterion that must be achieved under the given context.
+
+Only three (instead of SEI six) attributes, but understandable and precise.
 
 ### Summary
-**Quality scenarios** document and clarify the required quality attributes. They help to describe required or desired qualities of a system in a pragmatic and informal manner, making the abstract term “quality” more concrete, specific and tangible.
+**Quality scenarios** document and clarify the required quality attributes. 
+They help to describe required or desired qualities of a system in a pragmatic and informal manner, making the abstract term “quality” more concrete, specific and tangible.
+
+We propose you try the pragmatic and simple Q42-Quality-Scenario template for your own projects.

requirements/A/_posts/2000-09-03-access-find-function-in-3-secs.md

@@ -6,12 +6,22 @@ permalink: /requirements/access-find-function-quickly
 ---
 
 <div class="quality-requirement" markdown="1">
+#### Context/Background
 
-Users must be able to access the _find_ function within 3 seconds of accessing the interface.
+The system is a software application with a graphical user interface, accessible via mobile or desktop platforms.
+The application includes various functions, with the "find" function being a critical feature for locating specific types of data within the system.
 
-**Background**: Users operate the system via a graphical frontend (i.e. like in a typical mobile or desktop application).
-One important type of function within the system is _finding_ certain types of date.
+#### Source
 
+User interaction - A user accesses the find function from the application's main interface.
+
+#### Metric/Acceptance Criteria
+
+The "find" function must be accessible to users within 3 seconds of the interface loading.
+This can be measured by:
+*. Time from interface load completion to the "find" function becoming interactive and ready for use.
+*. Success rate: At least 99% of users should be able to access the "find" function within the 3-second timeframe.
+*. Consistency: This performance metric should be maintained across different devices and network conditions typical for the application's intended use.
 </div><br>
 
 

requirements/A/_posts/2023-03-18-accurate-estimate-of-contract-rate.md

@@ -7,14 +7,25 @@ permalink: /requirements/accurate-estimate-of-insurance-rate
 
 <div class="quality-requirement" markdown="1">
 
-**Scenario**: A user configures a health insurance contract in the online app.
+#### Context/Background
 
-**Reaction**: The system calculates a price estimate based on the currently available information. 
+The system is an online application for configuring health insurance contracts.
+The final price of the insurance rate needs to be determined by the backoffice employees of the insurance company due to legal and organizational reasons.
+This constraint cannot currently be relaxed.
 
-**Metric**: This estimate must be within a ±15% margin relative to the final price.
+#### Source
 
-**Background**: The final price of the insurance rate needs to be determined by the backoffice employees of the insurance company due to legal and organizational reasons. This constraint cannot currently be relaxed.
+User interaction: A user configures a health insurance contract in the online app.
 
+#### Metric/Acceptance Criteria
+
+The system must calculate a price estimate based on the currently available information.
+This estimate must be within a ±15% margin relative to the final price.
+This can be measured by:
+* Comparing the system-generated estimate to the final price determined by backoffice employees
+* Calculating the percentage difference between the estimate and final price
+* Ensuring that at least 95% of estimates fall within the ±15% margin
+* Regularly auditing a sample of contracts to verify compliance with this metric
 </div><br>
 
 

requirements/A/_posts/2023-06-21-add-new-product.md

@@ -7,15 +7,20 @@ permalink: /requirements/add-new-product
 
 <div class="quality-requirement" markdown="1">
 
-**Background**: Editor uses administration panel to add a new product to a webshop
 
-**Source**: Editor
+#### Context/Background
 
-**Stimulus**: Adds new product
+The system is a webshop with an administration panel for editors to manage products.
+Editors can add new products to the webshop through this administration panel.
 
-**Reaction**: Product is visible in the webshop in under 60 minutes
+#### Source
 
-**Metric**: The time taken for a newly added product to become visible and available for users in the webshop is 60 minutes or less
+Editor uses the administration panel to add a new product to the webshop.
+
+#### Metric/Acceptance Criteria
+
+The time taken for a newly added product to become visible and available for users in the webshop is 60 minutes or less,
+for at least 95% of newly added products.
 
 
 </div><br>

requirements/A/_posts/2023-07-03-accountability-detailed-audit-log.md

@@ -7,21 +7,31 @@ permalink: /requirements/detailed-audit-log
 
 <div class="quality-requirement" markdown="1">
 
-**Stimulus**: A user submits a request to access personal data stored in the system.
 
-**Environment**: System operates in compliance with privacy and data protection regulations.
+#### Context/Background
 
-**Response:** The system should maintain a detailed audit log of all user actions, including data access, modification, and deletion, along with associated timestamps and user identifiers. 
-This log should be tamper-proof, accessible only to authorized personnel, and retained for a minimum of five years.
+The system stores personal data and operates in compliance with privacy and data protection regulations.
+The system maintains detailed audit logs of all user actions related to personal data.
+These logs are crucial for ensuring accountability, transparency, and compliance with regulations.
+The logs facilitate the identification and investigation of any unauthorized or suspicious activities related to personal data.
 
-**Background:** In this scenario, the accountability requirement is described for a system that stores personal data and operates in compliance with privacy and data protection regulations. 
-When a user requests access to their personal data, the system should respond by maintaining a detailed audit log that captures all user actions related to data access, modification, and deletion. 
-The log should include timestamps and user identifiers, ensuring traceability and accountability for all data-related activities. 
-It should be tamper-proof and accessible only to authorized personnel to prevent unauthorized modifications. 
-Furthermore, the log should be retained for a minimum of five years, aligning with data retention requirements. 
+#### Source
 
-By meeting this accountability requirement, the system promotes transparency, facilitates compliance with regulations, and enables the identification and investigation of any unauthorized or suspicious activities related to personal data.
+User submits a request to access personal data stored in the system.
 
+#### Metric/Acceptance Criteria
+
+The system must maintain a detailed audit log of all user actions, including data access, modification, and deletion.
+The audit log must meet the following criteria:
+* Include associated timestamps and user identifiers for each action
+* Be tamper-proof to prevent unauthorized modifications
+* Be accessible only to authorized personnel
+* Be retained for a minimum of five years
+* Capture 100% of user actions related to personal data
+* Be searchable and retrievable within 24 hours of a request by authorized personnel
+* Undergo regular integrity checks to ensure no tampering has occurred
+* Be backed up securely to prevent data loss
+* Comply with all relevant privacy and data protection regulations
 </div><br>
 
 >This "requirement" describes a solution approach to accountability.

requirements/A/_posts/2023-07-03-authenticity-of-digital-document..md

@@ -7,19 +7,31 @@ permalink: /requirements/authenticity-of-digital-document
 
 <div class="quality-requirement" markdown="1">
 
-**Stimulus**: A user attempts to verify the authenticity of a digital document.
-
-**Environment**: System operates in a context where document integrity and trustworthiness are critical.
-
-**Response**: The system should provide a robust digital signature mechanism that verifies the authenticity and integrity of the document, ensuring that any modifications or tampering can be detected. 
-    Additionally, the system should maintain a secure and tamper-proof audit trail that records all document-related activities, including creation, modifications, and approvals, with timestamps and user identifiers.
-
-**Background:** In this scenario, the authenticity requirement is described for a system where document integrity and trustworthiness are crucial. 
-When a user attempts to verify the authenticity of a digital document, the system should respond by providing a robust digital signature mechanism. 
-This mechanism ensures that the document's authenticity and integrity can be validated, enabling the detection of any unauthorized modifications or tampering.
-
-Furthermore, the system should maintain a secure and tamper-proof audit trail that records all document-related activities. This includes the creation, modifications, and approvals of the document, along with timestamps and user identifiers. By capturing these details in the audit trail, the system enhances accountability and transparency, allowing users to track the document's history and ensuring that the document's authenticity can be reliably verified.
-
+#### Context/Background
+
+The system operates in an environment where document integrity and trustworthiness are critical.
+It provides functionality for users to verify the authenticity of digital documents.
+The system employs a robust digital signature mechanism to ensure document authenticity and integrity.
+A secure and tamper-proof audit trail is maintained for all document-related activities.
+
+#### Source
+
+A user attempts to verify the authenticity of a digital document.
+
+#### Metric/Acceptance Criteria
+
+The system must provide a robust digital signature mechanism and maintain a secure audit trail.
+The authenticity verification process must meet the following criteria:
+* Digital signature mechanism correctly verifies the authenticity and integrity of 100% of unmodified documents
+* Any modifications or tampering to a document are detected with 100% accuracy
+* The audit trail records all document-related activities, including creation, modifications, and approvals
+* Each audit trail entry includes accurate timestamps and user identifiers
+* The audit trail is tamper-proof, with any attempts at unauthorized modification being detected and logged
+* Digital signature verification process completes within 5 seconds for documents up to 10MB in size
+* Audit trail entries are created and logged within 1 second of the corresponding document activity
+* The system provides a clear, user-friendly interface for users to initiate and understand the results of the authenticity verification process
+* The audit trail is searchable, allowing authorized users to retrieve the complete history of a document within 30 seconds
+* The system maintains 99.99% uptime for the authenticity verification service
 </div><br>
 
 

requirements/A/_posts/2023-07-23-access-control-is-enforced.md

@@ -7,38 +7,38 @@ permalink: /requirements/access-control
 
 <div class="quality-requirement" markdown="1">
 
-### Stimulus 
-A user attempts to access a sensitive feature or confidential information within the system.
-
-### Environment 
-Multi-user environment with varying levels of user roles and permissions.
-
-### Response
-The system should enforce appropriate access controls based on the user's role and permissions. 
-If the user's role grants access to the requested feature or information, the system should allow access without any impediments. 
-However, if the user's role does not have the required permissions, the system should deny access and display a relevant and user-friendly error message. 
-Additionally, any access control violations should be logged and reported to authorized personnel for further investigation.
-
-
-### Background 
-In this scenario, the access control requirement is defined for a multi-user system with different levels of user roles and permissions. 
-When a user attempts to access a sensitive feature or confidential information, the system should respond by enforcing appropriate access controls.
+#### Context/Background
 
-Precise metrics to determine when the requirement is met include:
+The system operates in a multi-user environment with varying levels of user roles and permissions.
 
-**Authentication**: Users must be authenticated before accessing any sensitive data. Authentication should be based on a strong authentication method, such as multi-factor authentication (MFA) or biometric authentication.
+* Sensitive features and confidential information are present within the system.
+* Access control is crucial to maintain data security and privacy.
+* The system employs role-based access control (RBAC) to manage user permissions.
+* An audit trail is maintained for all access attempts to sensitive data.
 
-**Authorization**: The system should grant access to sensitive customer data based on the principle of least privilege. Authorized users should have only the minimum level of access necessary to perform their tasks.
+#### Source
 
-**Role-Based Access Control** (RBAC): Access to sensitive data should be determined by user roles. Precise roles should be defined, such as "Customer Service Representative," "Financial Analyst," and "Administrator," and access permissions should be assigned accordingly.
-
-**Data Classification**: Sensitive customer data should be classified based on its level of sensitivity (e.g., public, internal, confidential). Access controls should be configured according to these classifications, with stricter controls for highly sensitive data.
-
-**Audit Trail**: The system should maintain a detailed audit trail of all access attempts to sensitive data. This includes recording the user's identity, timestamp, accessed data, and the outcome (granted or denied). Audit logs should be tamper-proof and securely stored.
-
-**Access Revocation**: The system should allow authorized personnel to revoke access permissions immediately when necessary, such as in cases of employee termination or data breaches.
+A user attempts to access a sensitive feature or confidential information within the system.
 
-**Session Management**: Sessions should have a timeout mechanism to automatically log users out after a period of inactivity to prevent unauthorized access in the event a user leaves their session unattended.
+#### Metric/Acceptance Criteria
+
+The system must enforce appropriate access controls based on the user's role and permissions.
+
+The access control mechanism must meet the following criteria:
+* 100% of access attempts must be authenticated before granting access to any sensitive data
+* Multi-factor authentication (MFA) or biometric authentication is implemented for accessing highly sensitive data
+* User roles are precisely defined (e.g., "Customer Service Representative," "Financial Analyst," "Administrator")
+* Access permissions are assigned based on the principle of least privilege
+* Sensitive data is classified into at least three levels (e.g., public, internal, confidential)
+* Access controls are configured according to data classification, with stricter controls for highly sensitive data
+* 100% of access attempts (successful and failed) to sensitive data are logged in a tamper-proof audit trail
+* Audit logs include user identity, timestamp, accessed data, and outcome (granted or denied)
+* Authorized personnel can revoke access permissions immediately, with changes taking effect within 60 seconds
+* User sessions automatically timeout after a maximum of 30 minutes of inactivity
+* Access denials display a relevant and user-friendly error message within 2 seconds
+* 100% of access control violations are logged and reported to authorized personnel within 5 minutes
+* The system maintains 99.99% uptime for the access control service
+* Access control policy updates are applied system-wide within 5 minutes of being implemented
 </div><br>