QVscribe for Microsoft Excel

Everything you need to know about the installation and usage of QVscribe for Microsoft Excel can be found below.

Installation

QVscribe for Excel Installation

You will receive a license key and QVscribe download information from your Customer Success Manager upon completion of payment. If you did not receive your license key or QVscribe download, please contact support@qracorp.com.

The installation file contains the entirety of the QVscribe for Excel add-in.

Install QVscribe for Excel by following these steps:

  1. Right-click on the downloaded installer file. This will launch a dependency checker to ensure your system has everything it needs to run this version of QVscribe for Excel, and install any pre-requisite packages. Follow the on-screen instructions.

  2. Once the QVscribe installation wizard finishes, you will need to close and restart Excel to finish the installation.

The QVscribe Add-In should now be visible in your Microsoft Excel Home ribbon.

Activating your QVscribe for Excel

After installation, access QVscribe For Excel via the new QVscribe tab in the Excel ribbon.

The first time you access QVscribe you will see a window pop-up showing a “Getting Started” video. We suggest watching the short 90-second intro video to get a high-level overview of QVscribe, and you can press the Get Started button at the bottom of the window at any time to move on to the QVscribe activation screen as shown below.

QVscribe for Individual Activation

 If you have a single-user license, press the QVscribe for Individuals button and a screen to enter your license key will appear.

Enter your license key, and then press Validate.

A request file will then be placed on your desktop. Please send this license request to your Customer Success Manager. The request file is a secure key that allows the QVscribe license to work on your computer. You will be able to access QVscribe in the meantime if you select Skip activation.  You will have access to 5 days of trial usage before you need to insert your license.

Once you receive your license, select QVscribe for Individuals on your QVscribe ribbon, then Update License and insert your license file. The screen will show the name and expiration date for the license (as shown in the example to the right).Press Continue to finish the activation process.

QVscribe for Teams Activation

If you are part of an organization using QVscribe for Teams, press the QVscribe for Teams button. You will be prompted to enter the IP address to the QVscribe Teams Server in your organization. This address should be provided to you by your IT administrator.

After entering the IP address, please select whether you will be connecting via Active Directory or Local. Active Directory will automatically connect you to the server based on your computer login credentials. If you are using a Local connection, you will need to enter a Username and Password. This information should be provided to you by your IT administrator. Press Connect to your QVscribe for Teams Server.

Upon successful connection, you will see a “Server Validated” message.

If you are connecting locally, you will then be prompted to enter your username and password.

Press Continue to finish the activation process and to launch the QVscribe pane on the active document.

Marking Requirements

Selecting your requirements in QVscribe for Excel

In order for QVscribe to analyze your requirements, you must first add them to the QVscribe environment. This is done by either:

  • selecting a requirement cell and pressing Add

  • selecting an entire range of cells or an entire column containing requirements and pressing Add

It is important to define the column containing the requirement ID for these to be preserved with the analyzed requirements, this is done by assigning the column number in the pull-down beside the Add button.

If the Excel workbook has multiple sheets with requirements, the requirements are added per each active sheet. Once requirements from more than one sheet have been added to the list, you can select to view the list of requirements for all sheets or only for the active sheet as shown below.

Note that selecting a requirement from the list will also select it from the corresponding cell in the worksheet.

The total count of requirements in the Your Requirements list to be analyzed will be shown in the Analyze button under the list.

Removing Single Requirements from Analysis

You can remove requirements directly from the QVscribe Quality Analysis screen.

Each requirement row in the Quality Analysis screen has an ‘X’ that will immediately remove the requirement from the QVscribe environment (it will not affect the actual requirement on the document beyond removing the QVscribe mark from it). This is a useful feature if rogue sentences make it into the QVscribe environment.

Note that removing a single requirement will immediately invalidate the Consistency and Similarity analyses as these may depend on that requirement. You will need to rerun the analysis after removing a requirement in order to see the Consistency and Similarity results.

Requirement Analysis

Analyzing your requirements

Once you have selected all the requirement you would like to analyze and ensured that QVscribe is using the appropriate analysis Configuration for your document, press the Analyze # Requirements.

Once you press Analyze # Requirements a pop-up window will appear showing the analysis in progress. The duration of the analysis will depend on the number and size of requirements confirmed. This should not take longer than a couple of minutes.

QVscribe performs three distinct types of analysis on the selected requirements, each focusing on a key area:

1. Requirements Quality: Each requirement is assessed and scored based on the analysis configuration that encodes established requirements engineering standards, the INCOSE Guide for Writing Requirements and best practices. The quality analysis uses the following set of Key Quality Indicators in its algorithms.

Imperatives

Non-specific Temporal Words

Negative Imperatives

Continuances and Combinators

Vagues

Directives

Optional Escape Clauses

Justification(warning)

Optional Open-ended Clauses

Universal Quantifiers and Absolutes (warning)

Superfluous Infinitives

Passive Voice (warning)

Cross Referencing Pronouns

Incomplete sentence (warning)

Immeasurable Quantification

2. Term and Unit Consistency:

Terms: QVscribe detects and highlights all noun-phrases found in the requirements and displays them along with the requirements containing them, and along with any similar terms. This helps verify that domain-specific terminology is consistent throughout the document and that the correct terms are used in each requirement.

Units: QVscribe detects and highlights all units in the selected requirements based on the list of units in the QVscribe Configuration. The detected units are displayed by type, along with the requirements containing them. This helps assess that all units are correct and consistent throughout the requirements.

3. Requirements Similarity: QVscribe analyzes the syntax of each requirement and shows any requirements found that is similar to it. The level of similarity can be tuned higher or lower to help assess if duplicates or contradicting requirements are present.

QVscribe Quality Analysis

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.

Quality Analysis Details and Term Highlighting

Every requirement in the scorecard that has a score of less than 5 bars can be expanded to reveal details on what quality indicators issues led to the given score. The requirement within the main document will be selected and the issues will be highlighted. This helps you you understand where exactly the requirement is not meeting best practices.

The example above has the problematic terminology highlighted. There is the use of a negative imperative ‘shall not’, as well as superfluous infinities ‘limit’ and ‘capability’

Note: If some analysis results are inconsistent with your company standards, ensure that the QVscribe Configuration being used is appropriate for the document, or talk to your QVscribe administrator about creating a QVscribe configuration that more directly adheres to your specific standards.

Sorting and Filterings Quality Analysis Results

The value of the scorecard is especially evident when the results are sorted and filtered. This allows you to cut through the noise in the document and focus on the areas that need the most attention first.

To sort by Requirements or by Scores, click on the header of the desired column. Sorting by score can quickly let you see where the most problems are and the source of these problems.

You are also able to filter the results based on the individual quality indicator being affected in the requirements. To filter the results, press on the Issues pulldown list above the Score column and choose from any of the found issues.

QVscribe Consistency Analysis

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).

QVscribe Similarity Analysis

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.

Generating a report

The final step in using QVscribe is to generate an analysis report. To do this, press on Generate Report. A window will appear for you to set the location and file name of the analysis report, as well as configure how the report should present the analyst results. Once your settings are set, press Create.

The QVscribe analysis report includes:

  • Document title, analysis date, the configuration used, and the total number of analyzed requirements

  • Score Summary detailing the number of requirements with each score

  • Analysis Breakdown for each quality indicator and how many requirements had issued with it

  • The list of Individual Requirements with their corresponding scores, terminology highlighting, and
    analysis details

  • A detailed Appendix of the Configuration settings used during the analysis

  • A list of highly similar requirements displayed dependent on the Matching Strength Threshold chosen

Configuration

QVscribe Configurations

The way QVscribe analyses requirements and displays analysis results depends on the analysis configuration being used. To set a QVscribe configuration for analysis on the active document, select from the pull-down list.

In QVscribe for Individuals, QVscribe comes with a default analysis configuration. We recommend that you review and edit this configuration to create a configuration that adheres to your specific processes and standards.

In QVscribe for Teams, only users that have been assigned as Configuration Administrators in the QVscribe Team Server will be able to edit/create analysis configurations.

Navigating your Configuration Window

The QVscribe Configuration window contains four main tabs: Trigger Words, Unit Consistency, Exclusion Prefixes, and Templates.

There are also two other main tabs exclusive to QVscribe for Word: Tables and Key & Mouse Actions

The Trigger Words tab consists of sub-tabs, each representing a class of words/phrases corresponding to each key quality indicator used in the analysis and scoring of requirements.

Each Quality Indicator sub-tab consists of two lists of trigger words:

  • the list on the left labeled Your Words, which are the terms used during the QVscribe quality analysis to assess that quality indicator in the requirement

  • the list on the right labeled Example Words showing the set of most common trigger words to move to the Your Words list by selecting it and pressing the arrow button below the list (< )

Note that the Your Words list of trigger words comes pre-populated with the Example Words, but this should generally be modified to meet your specific requirements standards.

Making changes to your QVscribe Configuration

Adding a New Word/Phrase
To add a new word to the Your Words list click the Add button. Enter the word/phrase you want to add to the list and then click OK.

Editing Word/Phrase
To edit an existing trigger word, click on the word you want to edit in the Your Words list and click the Edit. Edit the word/phrase as needed and click OK.

Removing Word/Phrase
Click on the trigger word you want to remove from the Your Words list, and click the Remove button. Once all changes are completed, click OK on the QVscribe Configuration window to save the changes or Cancel to discard all changes.

A Note on Continuances and Directives
Continuances and Directives are quality indicators that may help in the analysis of requirements. There are different approaches to their use and QVscribe allows you to turn off their assessment so as to not adversely affect the requirements quality scores. Just check the Exclude from Analysis box.

Unit Consistency
Measurement units are key to the specification of qualities in requirements. QVscribe scans
through all marked requirements and detects any units within them based the user-configurable
list accessible in the configuration window. This list maintains the unit name, unit type, and common abbreviations.

Each unit can be enabled/disabled, edited, or removed. You can also add and edit units in this list by pressing Add or Edit and entering the new details for the unit. Selecting whether the unit is part of the International System of Units simply allows for the filtering of units present in a document based on these SI or not.

Exclusion Prefixes
In requirements documents, there are often paragraphs relating to the main requirement specification that are meant as comments, rationales, or explanations meant to provide context to the related requirement, but generally, do not follow proper requirements best practices.

To address this, the Exclusions Prefixes tab
helps by defining in QVscribe what term(s) is(are) used to define these context paragraphs so they are not included in the analysis of the actual requirement, and thus not skew the requirement’s score.

Note: the paragraph will need to begin with this prefix for QVscribe to relate it to the requirement.

QVscribe Toolbar

QVscribe Toolbar and Pane in QVscribe for Excel

Once the QVscribe for Excel add-on has been successfully installed and activated, you will see the QVscribe toolbar as a new tab in the Excel ribbon. The buttons function as follows:

  • QVscribe – opens/closes the QVscribe pane

  • QVscribe for Individuals/Teams – shows licensing information

  • The pull-down list – shows the available QVscribe analysis configurations for the user along with save/edit buttons. In QVscribe for Teams, these buttons may or may not be available to all users, depending on the team permissions setting

  • Remove All Marks – clears any existing QVscribe metadata from the document

  • QVscribe Help – button will open a window to access the help centre, log files and telemetry data

The QVscribe pane appears on the right-hand side of your Excel screen. In the QVscribe pane you are able to select requirements for analysis, navigate all the analysis results, and generate reports.

Note that the QVscribe pane can be undocked and moved to any of the other sides of the Excel window by simply dragging it from the top section of the pane to a new side. The undocked QVscribe pane can also be left as a floating window on your screen or moved to a second screen to maximize the document view.

QVscribe Help Centre

The QVscribe Help window provides access to the same brief intro video shown prior to activation. This is useful when a new user is accessing a system with QVscribe already installed. In case a video player is not detected, a URL will be provided to see this video online.

A URL to the QVscribe Help Centre is also provided in this window. The Help Centre contains the same information as the user guide but in a categorized format.

If you experience errors or unexpected behaviour in QVscribe, you can also generate Log Files that may be useful to QRA engineers to help troubleshoot and find the root cause. You can save the log files and then attach them in an email to support@qracorp.com along with a description of the issue you have encountered.

In order to improve the functionality of QVscribe, non-user specific application usage data is collected. This data is being collected to help improve product features, performance and your overall experience. The data collected can only be provided to us by user action and is not automatically collected. Your specific user data is not being captured; you can look at the data being collected by clicking on View QVscribe Telemetry. You can send this data to us to help with QVscribe features and improvements, by clicking on Send QVscribe Telemetry.