.png?height=120&name=4.0%20(7).png)
✅ Ready to see QVscribe in action?
This section will walk you through how to analyze a requirement for the first time using the Web extension. You’ll learn how to:
✨ Run an analysis
🔍 Interpret your results, including the quality score for your requirements
🧠 Check for consistency in language and units
🔁 Spot potential duplications or contradictions
It’s a quick and easy way to start improving your requirements right away! ✅
Chapter 3
Chapter 3.1: Quality Analysis
🎥 Video coming soon
A walkthrough video for this section is currently in the works. Check back shortly!
Once selected, the QVscribe summary dashboard will open. The 5-level scoring system gives you a clear snapshot of which requirements need the most attention and which are already aligned with best practices. 📊
💡 Use this view to:
-
Quickly identify which requirements to prioritize 🔍
-
Open specific requirements directly in your web-based tool
-
Focus your review on the most impactful areas
Click Quality Analysis on the right-side panel of the Summary View to get to the analysis. 👈
🛠️ If you're not sure how to prioritize certain scores or issue types, this article is a great starting point.
Interacting with Quality Analysis
Interacting with Quality Analysis
After selecting Quality Analysis, QVscribe displays results for each requirement or item in the order they appear in your document. You can click on any individual requirement to view its detailed feedback.
At the top of this view, you'll find two helpful tools to refine your focus:
-
Filters: Narrow results by quality score levels or zero in on specific issue types that matter to you
-
Sorting: Adjust the order to quickly spot which requirements may need your attention first
You can use filtering and sorting tools to focus on the most relevant requirements for your review. These tools help you cut through the noise and zero in on what needs your attention most. 🎯
🔍 Filter Requirements
The Filter Requirement drop-down lets you display only the requirements or items that meet specific criteria. You can filter by:
-
✅ QVscribe score (1–5)
-
⚠️ Specific Quality Issues detected during analysis
Selecting any option instantly narrows the list so you can concentrate on requirements that need review.
↕️ Sort Order
The Sort Order drop-down helps you organize the requirements/items list in a way that makes sense for your workflow. You can sort by:
-
📄 Document order
-
🟢 Quality score
-
🔔 Number of warnings
These controls make it easy to prioritize your review and act where it matters most. 💡
✅ Quality Analysis Details
QVscribe helps you dig into the why behind each score so you can take clear, targeted action. When reviewing an analyzed requirement or artifact, you’ll see a breakdown of the specific issues that contributed to the quality score. ⚙️
🔔 See What Triggered Each Alert
-
When an artifact has one or more alerts, selecting any alert will highlight the specific part of the text that triggered it.
-
For example, if the alert is for “Cross-Referencing Pronouns”, QVscribe will highlight exactly which word(s) are causing the issue. 🕒
Alert Order & Filtering
-
Alerts appear in the order they are found in the requirement text.
-
Use the right-side filter menu to narrow down alerts by type, like “Multiple Imperatives” — so you can focus on one issue at a time.
-
To return to a full view, simply select “All Alerts.”
Check out this article for a deeper explanation of how scoring works and how you can use it to guide improvements. 📘
🔍 Start with the Score and Alerts
This requirement has been given a score of 1/5. The alerts help explain why:
-
❗ Multiple Imperatives (e.g., multiple uses of “shall” in one sentence)
-
❓ Cross-Referencing Pronoun (“it” is unclear)
-
⚠️ Passive Voice — while this doesn’t affect the score, it’s still worth considering.
🦖Coach QRex: Passive voice can be acceptable in some cases, but many teams prefer to avoid it for clarity.
📝 Fixing the Issues One by One
-
Multiple Imperatives
-
Click the alert card for a brief explanation, and select Learn More for deeper guidance.
-
In this case, after a quick team review, we realize the fallback condition isn’t necessary — switching to Pace-Now mode already handles that.
-
✅ Change made! The requirement’s score jumps from 1/5 to 3/5.
-
-
Cross-Referencing Pronoun
-
The word “it” is vague. We clarify that “it” refers to the pacemaker system.
-
🎉 That adjustment brings the score to 5/5!
-
📈 From 1 to 5 — A Success Story
By following the alerts and applying expert judgment, we turned a low-quality requirement into a top-tier one. This is a perfect example of how QVscribe supports better writing without replacing the human touch. 💬💡
Go to the beginning of Chapter 3
Chapter 3.2: EARS Compliance and Templates
🎥 Video coming soon
A walkthrough video for this section is currently in the works. Check back shortly!
Unclear, vague, or overly wordy requirements can lead to confusion, mistakes, and costly rework. EARS (Easy Approach to Requirements Syntax) helps solve this by adding clarity and structure to natural language requirements. It makes requirements clear, concise, and actionable! ✍️✅
EARS uses five core templates to define system behaviour in a simple and structured way. These templates cover both desired actions and unwanted behaviours, ensuring your requirements are clear and easy to follow. Read more here!
EARS Templates Breakdown 🛠️
Ubiquitous 🌍
- Always true: The system performs an action at all times.
- Template: The <system> <imperative> <system response>
- Example: The Garage Door Opener shall display the Power Status.
Event-Driven ⏲️
- Triggered by an event: The system reacts when a specific event occurs.
- Template: When <trigger>, the <system> <imperative> <system response>.
- Example: When the Open Button is pressed, the Garage Door Opener shall open the Garage Door.
Optional Feature 💡
- Conditionally enabled: The system performs an action if a feature is present.
- Template: Where <feature is included>, the <system> <imperative> <system response>.
- Example: Where the Keypad is installed, then the Garage Door Opener shall require a passcode to open the Garage Door.
Unwanted Behaviour 🚫
- Mitigating negative events: The system reacts to unwanted behaviour or conditions.
- Template: If <trigger>, then the <system> <imperative> <system response>.
- Example: If the Sensor detects an obstruction, then the Garage Door Opener shall stop the Garage Door.
Complex Requirements 🔄
As you break down requirements, you may need to combine multiple templates. Complex requirements often use combinations of the EARS patterns to describe system behaviour based on several conditions.
Example:
While the Garage Door is closing, when the Open Button is pressed, the Garage Door Opener shall stop the Garage Door.
This combines State-Driven and Event-Driven templates.
Template: While <pre-condition(s)>, when <trigger>, the <system> <imperative> <system response>.
✅ EARS Compliance in QVscribe
QVscribe automatically checks whether your requirements/items follow the EARS standard as part of its Quality Analysis.
Here’s how it works:
-
🛑 EARS Alerts
If a requirement/item is not EARS-compliant, an alert will appear in the Alert Column of the analysis panel. -
🔍 Expanded Alert Details
Click on the alert to see more information about why the requirement isn’t compliant and what could be improved.
-
📋 EARS Type Detection
If the requirement is EARS-compliant, QVscribe will also identify the specific EARS pattern type in the right-hand panel, such as Ubiquitous, Event-Driven, or State-Driven, among others.
Why it matters:
Using EARS helps create clear, concise, and consistently formatted requirements, reducing ambiguity and improving communication across teams. QVscribe makes it easy to adopt and maintain this best practice. 🌟
📋 EARS Templates in Authoring View
QVscribe makes it easy to write well-structured requirements using built-in EARS Templates, helping you get started with clear, consistent phrasing from the very beginning. ✍️✨
How to Use EARS Templates in QVscribe
-
🔽 Select Template Type
While in Authoring View, you’ll see an option to insert an EARS template.
Once you’ve found the right fit, just click the grey insert icon to add the EARS template directly into your requirement or item.
After insertion, the template becomes part of your text — you can edit it however you'd like! QVscribe will automatically check for conformance with EARS standards and score it based on your current configuration.
🦖 Coach QRex: EARS (Easy Approach to Requirements Syntax) helps streamline the requirements writing process by focusing on content rather than structure. By following EARS templates, you can quickly organize your thoughts, improve clarity, and ensure consistency. This lets you spend less time on formatting and more time refining your requirements' core message!
Go to the beginning of Chapter 3
Chapter 3.3: Glossary of Defined Terms
🎥 Video coming soon
A walkthrough video for this section is currently in the works. Check back shortly!
📚 Glossary: Ensuring Consistency Across Your Requirements
The Glossary in QVscribe helps maintain consistency by providing clear definitions for important terms, acronyms, and phrases. Whether you're working with common terminology or specialized jargon, the Glossary ensures everyone is on the same page.
🔍 Viewing the Full Glossary of Defined Terms
📂 Accessing the Glossary
You can view the full list of defined terms in the Configuration Panel of the web extension.
🖋️ Seeing Glossary Terms in Your Analysis
👀 Spotting Defined Terms
In the Quality Analysis window, terms from the Glossary are underlined in green for easy identification!
➡️ Tip: Click the underlined term in your requirement or select the matching card in the side panel to view the full definition.
🦖Coach QRex: The Glossary is tied to your Configuration, so only Configuration Authors can edit it, but all users can view the definitions within the extension and analysis window.
Go to the beginning of Chapter 3
Chapter 3.4: Consistency Analysis
🎥 Video coming soon
A walkthrough video for this section is currently in the works. Check back shortly!
🔍 QVscribe’s Consistency Feature: Keeping Your Requirements Aligned
QVscribe’s Consistency feature includes two powerful types of analysis: Term Consistency and Unit Consistency.
Use Case: Term Consistency and Glossary
These analyses are available in the Summary View and offer sortable, searchable lists of terms and units found in your requirements/items, helping ensure clarity and uniformity across your document.
What It Does:
Displays all domain-specific nouns and noun phrases in your document, along with a count and the number of similar terms detected.
How to Use It:
You can search for a specific term using the magnifying glass icon, and organize terms by various options, such as:
- 📚 Alphabetical Order: Default display, sorted alphabetically.
- 🔢 Most Occurrences: Lists terms by the number of times they appear.
- 🔄 Most Similar: Shows terms based on their similarity across requirements/items.
- 🎯 Highest % Match: Sorts terms by their similarity percentage.
Exploring Terms:Click any term to see all requirements/items where it appears. You can also view similar terms and their % similarity, which helps verify their correctness across the document.
Real-Time Tuning:
Adjust the Matching Strength Min and Max settings in the User Settings section to define the tolerance for term similarity. A 100% strength means only identical terms are considered similar, while a lower strength will increase the number of terms flagged as similar.
📖 Term Consistency & Glossary Use Case
-
Identifying Potential Issues:
After sorting by Most Occurrences, you notice the term “User” appears multiple times. Given the context of a Pacemaker System Specification, it’s unclear who “User” refers to (e.g., patient, doctor). This ambiguity makes the term potentially confusing. -
Checking the Glossary:
Searching for “Patient” reveals that it’s already defined in the Glossary. Now, “User” can be defined and added to the Glossary for clarity. -
Updating Glossary:
By adding the term “User” to the Glossary, everyone will be on the same page about the meaning of the term in the document.
📏 Unit Consistency
What It Does:
Lists all units detected in your document, including their type (e.g., metric or imperial) and total count.
How to Use It:
You can search for a specific unit and organize units by:
-
-
🌍 All: Displays all identified units.
-
🧮 International System of Units (SI): Displays only SI units.
-
❌ Inconsistent with SI: Shows units that aren’t part of the SI system (e.g., imperial units).
-
Exploring Units:Click on any unit to see where it appears in your requirements/items. The unit will be highlighted for easy identification.
🦖Coach QRex: Configuration Authors can update unit consistency at any time in the Configurations section of the QVscribe Browser extension.
Go to the beginning of Chapter 3
Chapter 3.5: Similarity Analysis
🎥 Video coming soon
A walkthrough video for this section is currently in the works. Check back shortly!
🔄 Similarity Analysis: Spotting Duplicates & Contradictions
The Similarity section in QVscribe helps you identify requirements/items that are similar to one another, helping you catch any potential duplications or contradictions. This analysis is essential for keeping your requirements consistent and clear.
🔍 How Similarity Analysis Works
What It Does:
The Similarity section lists your artifacts and shows how many similar ones exist. The number of similar requirements/items is displayed beside each item in the list.
Sorting Options:
You can sort the requirements/items by:
-
📜 Order of Appearance: Default sorting, shows items in the order they appear.
-
🔢 Number of Similar: Sort by the number of similar requirements/items found.
-
📊 Highest % Match: Sort by the highest percentage of similarity.
Exploring Similarity:
-
When you expand a requirement/item, its similar items are displayed on the right, along with a similarity percentage.
-
Clicking on any similar requirement/item shows it below the original, with differences highlighted in light purple for easy comparison.
Matching Strength Settings:The Matching Strength minimum and maximum can be adjusted in the User Settings of the QVscribe Browser Extension. This setting lets you control how similar two requirements/items need to be in structure and terminology.
🦖Coach QRex: Adjust the Matching Strength to 95-100% to quickly identify exact duplicates — perfect for spotting copy-pasted requirements that may have been left behind unintentionally. Lower the strength to 85–95% to catch near-duplicates that could lead to conflicting interpretations.
🧠 Similarity Analysis Use Case: Duplicate or Missing Context?
-
Starting from the Summary View:
Open the Similarity Analysis and sort the list by Highest % Match to find the most similar pairs of requirements.
-
Finding 100% Similarity:
In this example, you find two requirements that are 100% identical. Time to investigate! -
Investigating the Identical Requirements:
-
When you click on the pair, you see them side-by-side, and any differences would be highlighted in light purple. Since they’re identical, the next question is: why are they duplicated?
-
-
Checking Context:
-
Upon investigation, you realize one requirement refers to a Pace Now Pace Parameter, and the other refers to a POR Pace Parameter.
-
The context for these two parameters should be included directly in the requirements so they make sense on their own.
-
-
Fixing the Issue:
-
To clarify the requirements, you add the specific parameter details into each one, making each requirement self-contained and clear without needing to reference another.
-
📌 What to Do After Finding a Duplicate or Contradiction
Identifying a duplicate or contradiction is just the first step — deciding what to do next is where things really count.
To help you take the right action, use the Similarity Analysis Workflow Diagram above. It walks you through key questions like:
-
Do the requirements truly say the same thing?
-
Is the context different (e.g., different systems, modes, or conditions)?
-
Should they be merged, clarified, or removed?
✅ Use this workflow to decide whether to:
-
Keep both — if they refer to different contexts (but update them to stand alone clearly).
-
Merge into one — if they duplicate meaning with slight variations.
-
Delete one if the duplicate is unnecessary or outdated.
🦖Coach QRex: Always check with your team or refer to project documentation if you're unsure which version is most accurate.
📘 Summary:
In this chapter, you've learned how to leverage QVscribe’s powerful analysis tools to ensure your requirements meet the highest standards. Here’s a quick summary of the key features:
-
Quality Analysis: You now know how to evaluate the quality of your requirements, identifying areas that need improvement, such as clarity and consistency.
-
EARS Compliance & Templates: We explored how QVscribe helps you follow the EARS methodology and how to easily insert EARS templates into your requirements.
-
Glossary: You’ve seen how QVscribe’s Glossary ensures consistency by defining key terms across your project.
-
Term & Unit Consistency Analysis: You learned how to use QVscribe to track and maintain consistency in terminology and measurement units throughout your requirements.
-
Similarity Analysis: Finally, you discovered how to identify and address duplicated or conflicting requirements to maintain clarity and prevent errors.
By mastering these tools, you're now equipped to write more precise, consistent, and high-quality requirements that are ready for implementation. 🌟
Go to the beginning of Chapter 3