Articles related to commonly used features in QVscribe
The Quality Analysis tab shows a scorecard where each row corresponds to a marked requirement in the document along with its quality score. The 5-level scoring gives you a succinct picture of which requirements need the most attention and which ones adhere to best practices.
The Quality Analysis uses the following set of Key Quality Indicators in its algorithms to score each requirement.
|
Quality Indicator |
Description |
Best Practice |
Recommendation |
|
Imperatives |
Words and phrases that command that something must be done. |
A proper requirement has exactly one imperative. |
Ensure a single imperative is present in your requirement or split a requirement with more than one imperative into multiple requirements. |
|
Negative Imperatives |
Words and phrases that command that something must not be done. |
A proper requirement does not use negative imperatives as it is difficult to verify. |
Restate requirements with negative imperatives as one or more requirements with (positive) imperatives. Specify what the system shall do, not what it shall not do. |
|
Vagues |
Words and phrases that are imprecise, unclear, and ambiguous. They introduce uncertainty and leave room for multiple interpretations. |
A proper requirement does not use vague words or phrases. |
Restate the requirement with vague words as one or more requirements with clear and definite intent. |
|
Optional Escape Clauses |
Words and phrases that loosen the requirement specification and give latitude in implementation, reducing control and increasing risk. |
A proper requirement does not use optional words or phrases. |
Replace optional escape clauses with a verifiable statement and mark as required or optional as intended. |
|
Optional Open-Ended Clauses |
Open-ended clauses say that there is more required without stating exactly what. Open-ended clauses can lead to ambiguous, unverifiable requirements that do not reflect accurately the stakeholder expectations. |
A proper requirement does not use open-ended clauses. |
Replace the open-ended clause with the information that is being alluded to. |
|
Superfluous Infinitives |
Additional and unnecessary verbs or verb phrases in the requirements. |
A proper requirement should avoid superfluous infinitives. |
Remove superfluous verbs that cause verification issues. |
|
Cross-Referencing Pronouns |
Word and phrases to reference a person or an object without specifying who or what it is; for example, words such as “it”, “this”, “that”, “he”, “she”, “they”, and “them.” |
A proper requirement should avoid the use of pronouns and cross-referencing pronouns. |
Repeat nouns in full instead of using pronouns to refer to nouns in other requirements. |
|
Immeasurable Quantification |
Words or phrases that indicate an unmeasured quantification, such as” great”, "small",” medium-sized”,” best practice”, and ”user-friendly.” |
A proper requirement should avoid the use of immeasurable quantifiers. |
Replace with a quantity that can be objectively measured. |
|
Non-specific Temporal Words |
Words and phrases that reference non-specific timing, such as “eventually”, “until”, and “before”. These words are not verifiable and can cause confusion or unintended meaning. |
A proper requirement does not use non-specific timing references. |
Replace with specific timing constraints. |
|
Continuances & Combinators |
Word and phrases that follow the requirement’s imperative and introduce more detail to the specification. |
A proper requirement avoids excessive use of continuances (generally no more than two). |
Restate requirements with excessive use of continuances as multiple requirements each with simpler specifications. |
|
Directives |
Words and phrases pointing to information that aims to strengthen and clarify the specification, such as examples, tables, figures, or reference to other sections in the document. |
When necessary, a proper requirement uses directives to increase the understanding and clarity of context. |
Assess the need and the benefit of directives in the requirement. Careful and clear use of directives is recommended. |
|
Universal Quantifiers & Absolutes |
Words or phrases that generalize a quantity or quantities relating to a subject. |
Universal quantifiers should be used carefully and sparingly as they make a requirement difficult or impossible to verify without a thorough understanding of the context. |
Unless clear by its context, aim to restate the requirement with specific values for any quantities mentioned. NOTE: QVscribe will show this indicator as a warning and will not affect the score. |
|
Justification |
Extra information that is not needed within the requirement and that define a purpose for why the requirement exists. |
Information that defines why a requirement exists should not be within the requirement itself. Rather, this extra information should be defined within an accompanying "rational statement”. |
Remove information regarding purpose/justification from the requirement – add this information to the rationale statement or create a new rationale. NOTE: QVscribe will show this indicator as a warning and will not affect the score. |
|
Passive Voice |
A sentence written in passive voice has a receiver-acted-by- doer structure, rather than a more direct doer-acts-on-receiver structure. |
Requirements should be written in active voice and passive voice should be avoided. |
Restate the requirement into a doer-acts-on-receiver structure. NOTE: QVscribe will show this indicator as a warning and will not affect the score. |
|
Incomplete Sentences |
Incomplete sentences are such where the object, action, or subject may be poorly specified or missing altogether. |
Incomplete sentences should be avoided in general. |
Read the incomplete sentence and add the necessary details such that the object, action, and subject are clearly identified in the requirement. NOTE: QVscribe will show this indicator as a warning and will not affect the score. |
The Consistency tab shows the results of the terminology and unit consistency analysis. This analysis displays terms and units enumerated and in sortable and searchable lists. Each term or unit in the list can be expanded to show the corresponding requirements where the term or unit was found.
All found terms and phrases that appear to be domain-specific are displayed, along with a total count and number of terms similar to it.
This similarity can be tuned in real-time with the Matching Strength slider. The Matching Strength gives the tolerance in the assessment of term similarity, such that a Matching Strength of 100% means the terms have to actually be identical for them to be considered similar, and as this Strength is decreased, then more terms will be considered similar.
The terms in the Consistency tab can also be explored by double-clicking on them to show all requirements where that term appears, as well as a list of similar terms and the %-similarity for each. Each of these similar terms can in turn also be expanded to show the requirements where it appears. This helps rapidly verify that these similar terms are valid in their own right, and reside in the correct requirements.
The Unit Consistency results display all units detected, along with their type categorization and total count. Each unit on the list can be expanded to show the requirements where it was found and highlight the unit within. This helps ensure that the right unit is in the right requirement and that there is also consistency in the system of units used throughout the document (i.e. metrics or imperial).
The Similarity tab shows the results of the requirement similarity analysis. The number of similar requirements found is shown along with each requirement in the list and expanding a requirement in the list displays its similar requirements along with a percentage of how similar they are to each other.
Similar to the term similarity function in the Consistency tab, a Matching Strength slider lets you adjust how close requirements need to be in structure and terminology to be considered similar. It is useful to try different Strength settings within 75% to 95%. This will display requirements that may contradict each other. You can also set the Matching Strength to 100% to review if there are any identical requirements
When compared, the two similar requirements will be displayed at the bottom of the screen where the similarities and differences are highlighted. All similarities are highlighted in red and all differences are highlighted in green.
Available to those who have QVscribe for Teams, QVscribe provides assistance to authors of requirements based on the Easy Approach to Requirements Syntax (EARS), with both EARS templates and a conformance check against these EARS templates.
Within the QVscribe ribbon, QVscribe for Teams users will have access to an EARS templates button. When you want to author a requirement, you have the ability to select an appropriate EARS template from the list.
When a template is selected it will appear at the cursor location on the document. See example below.
You can then easily fill in the areas in the template to create a well-structured requirement.
All 12 EARS templates are described in detail below.
|
EARS Type |
Description |
Template |
|
Event-driven |
An Event-driven requirement is activated when a triggering event is detected at the system boundary |
WHEN <trigger> the <system name> shall <system response> |
|
Option |
An Option requirement is used for systems that include a particular feature |
WHERE <feature is included> the <system name> shall <system response> |
|
State-driven |
A State-driven requirement is active while some pre-condition remains true |
WHILE <pre-condition> the <system name> shall <system response> |
|
Ubiquitous |
A Ubiquitous requirement is continually active |
The <system name> shall <system response> |
|
Unwanted behaviour |
An Unwanted Behaviour requirement defines the required system response to an unwanted external event |
IF <trigger> THEN the <system name> shall <system response> |
|
Complex |
A Complex requirement contains a combination of the basic EARS patterns |
See table 3 below |
|
Complex EARS Template |
Label |
|
WHERE <feature is included> WHILE <pre-condition> IF <trigger> THEN the <system name> shall <system response> |
Optional feature, state-driven, and unwanted-behaviour |
|
WHERE <feature is included> WHILE <pre-condition> WHEN <trigger> the <system name> shall <system response> |
Optional feature, state-driven, and event-driven |
|
WHERE <feature is included> WHILE <pre-condition> the <system name> shall <system response> |
Optional feature, and state-driven |
|
WHERE <feature is included> WHEN <trigger> the <system name> shall <system response> |
Optional feature, and event-driven |
|
WHERE <feature is included> IF <trigger> THEN the <system name> shall <system response> |
Optional feature, and unwanted-behaviour |
|
WHILE <pre-condition> IF <trigger> THEN the <system name> shall <system response> |
State-driven, and unwanted-behaviour |
|
WHILE <feature is included> WHEN <trigger> the <system name> shall <system response> |
State-driven, and event-driven |
In conjunction with EARS templates, QVscribe can automatically check how closely requirements conform with EARS templates. This helps you assess if the requirements have good structures or if the requirements need to be clarified and further structured.
When you click and expand a requirement in the analysis window, you will also see information on EARS conformance. You will see either a drop-down stating EARS – ‘Template type’, Non-conforming, which means that the requirement does not conform with any EARS templates, or you will see EARS – ‘Template type’, describing which template this requirement conforms to along with what parts of the requirement correspond to the different elements of that EARS type structure.
To include EARS conformance check in the quality analysis of your requirement, just check the “Include in Analysis” box in the Templates tab of the Configuration window.
If the EARS conformance check does not align with your needs or approaches, you can un-check the “Include in Analysis” box in the Templates tab to turn this feature off from your analysis.
Note: The EARS templates and conformance checking features are only available for users with QVscribe for Teams.