.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 MS Office and Excel. 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.0: Analyze your Requirements
🎥 Video coming soon
A walkthrough video for this section is currently in the works. Check back shortly!
Once you’ve selected all the requirements you want to analyze ✅ and confirmed that QVscribe is using the right Configuration for your document, go ahead and click Analyze # Requirements to get started!
Once you click Analyze # Requirements, a pop-up window will appear showing the analysis in progress. The time it takes will depend on the number and size of the requirements, but it should only take a couple of minutes ⌛.
Chapter 3.1: Quality Analysis
🎥 Video coming soon
A walkthrough video for this section is currently in the works. Check back shortly!
Quality Analysis tab
The Quality Analysis tab displays a scorecard where each row represents a marked requirement along with its quality score. The 5-level scoring system gives you a clear overview of which requirements need improvement and which ones follow best practices.
🛠️ If you're not sure how to prioritize certain scores or issue types, this article is a great starting point.
🔍Sorting and Filtering
The scorecard becomes especially useful when you sort and filter the results. This helps you quickly focus on the requirements that need the most attention.
To sort by requirement or score, simply click the column header. Sorting by score is a great way to quickly identify the areas with the most issues and understand where improvements are needed.
You can also filter the results based on the specific quality indicators affected by the requirements. To do this, click the Issues dropdown above the Score column and select any of the listed issues to narrow your view.
✅ 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. 🕒
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
EARS compliance alerts are displayed under each requirement, alongside the Quality Score and Quality Warning alerts. -
🔍 Expanded Alert Details
Click on the alert to learn more about why the requirement is or isn’t compliant, and find suggestions for improvement.
-
📋 EARS Type Detection
If the requirement is EARS-compliant, QVscribe will also identify the specific EARS pattern type, 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. 🌟
How to Use EARS Templates in QVscribe
Within the QVscribe ribbon, users can access the EARS templates button. When writing or rewriting a requirement, simply select the appropriate EARS template from the list.
When a template is selected, it will appear at the cursor location on the document. See the example below.
You can then easily fill in the areas in the template to create a well-structured requirement.
🦖 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!
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 second tab of the Configuration Window, which you can access from the MS Office Ribbon by selecting either 'Open Configuration' or 'Edit Configuration'."
🖋️ Seeing Glossary Terms in Your Analysis
👀 Spotting Defined Terms
When viewing individual requirements, terms from the Glossary are highlighted in green (MS Word) or bolded, underlined and coloured green (MS Excel) for easy identification!
➡️ Tip: Click the Glossary Term in the Quality Analysis panel, and QVscribe will isolate that word within your requirement.
🦖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 MS Office Ribbon.
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
This analysis displays terms and units enumerated 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.
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.
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 Slider 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. A bit further down the list, you’ll also see that “patient” appears separately, adding to the confusion. -
Checking the Glossary:
Further investigation reveals that “patient” is 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).
-
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 MS Office Ribbon.
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 tab displays the results of the requirement similarity analysis. Each requirement shows the number of similar entries found, and expanding a requirement reveals its matches along with a percentage indicating how closely they resemble each other.
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.
Exploring Similarity:
-
When you expand a requirement/item, its similar items are displayed on the right, along with a similarity percentage.
-
When two similar requirements are compared, they are shown at the bottom of the screen, with similarities highlighted in purple and differences highlighted in yellow..
The Similarity Threshold slider lets you control how closely requirements must align in structure and language to be flagged as similar.
🦖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 tab and adjust the Similarity Threshold slider 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