QVscribe for Microsoft Word

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

Installation

QVscribe for Word 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 Word Add-in.

Install QVscribe for Word by following these steps:

  1. Right-click on the downloaded QVscribeForWordInstaller_[version].exe file. This will launch a dependency checker to ensure your system has everything it needs to run this version of QVscribe for Word 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 Word to finish the installation.

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

Activating your QVscribe for Word

After Installation, access QVscribe for Word via the new QVscribe tab in your Word Home ribbon.

The first time you access QVscribe you will see a window pop-up showing a ‘Getting Started’ video. .

You will then be prompted to select your license type.

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 (including the dashes), 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 Team 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 Word

In order for QVscribe to analyze your requirements, you must first add them to the QVscribe environment. This can be done in two ways:

  • Manually highlight each requirement and add it

  • Use Requirements Finder to automatically detect the requirements based on a few initial examples you give it

Manually adding requirements

To manually add a requirement you can perform the following steps:

  1. Highlight the entire requirement and any rationale or comments preceding it, and press Add

  2. Double-click on single-paragraph requirements to directly add them to the list

  3. Double-click on the first paragraph of multi-paragraph requirements then hold shift and double-click the other paragraphs of that requirement to include them all within the requirement.

These manually added requirements are immediately placed in the Checked and Available to be Analyzed list, and as the name states, they are ready to be analyzed.

Using Requirements Finder

QVscribe for Word includes a requirements auto-detection feature called Requirement Finder that helps you rapidly locate and highlight all requirements in the document. The found requirements can be reviewed before marking them for analysis.

Note that if the document does follow Requirement writing best practices and does not have any requirement identifiers, nor do all requirements begin with a common word or phrase, Requirements Finder may be ineffective. We suggest that you manually add your requirements.

How it works: Requirements Finder looks specifically at patterns in the requirement identifiers of the sample requirements you initially selected and uses these patterns to find the remaining requirements.

For this reason, it is best if the requirements in the document have alpha-numeric requirement identifiers preceding them, such as R10.3, 2.3.34.2, 10T-34R, and Req. The example below demonstrates a typical sample of requirements with good identifiers:

[EC-LMR-RCS-030] Remote Commanding: The Remote Control Station shall accept and send …
[EC-LMR-COM-020] Delay Tolerance: The Lunar Exploration Light Rover control shall …
[EC-LMR-FNC-012] Power-up: Upon command, the Lunar Exploration Light Rover shall …

From these samples, Requirement Finder infers the common pattern ‘[EG-LMC-’ and uses it to search for other requirements in the document that begins with that same pattern.

What you do: Select 3 well-spaced requirements to set a proper pattern, then select Requirements Finder. Once the Requirement Finder process is finished, you can navigate the list of found requirements to ensure all have been properly detected.

You will notice that the auto found requirements are shown greyed out, this is because auto-found requirements are not yet marked for analysis. Requirements detected with Requirement Finder must first be reviewed before being marked.

You can individually mark specific found requirements by double-clicking on them in the Found & not Checked list. This checks them and moves them to the Checked & Available to be Analyzed list.

If you want to check all found requirements at once, you can click on the Check All button.

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.

Removing all Marked Requirements in QVscribe for Word

When using QVscribe, marks are added to the document’s metadata that outline the selected requirements. These marks are an extremely useful tool in gathering all requirements into one easily accessible and navigable list. The marks are also used for the analysis and are a helpful aid when working within the analysis results.

In some instances, you may need to create a clean copy of a document that has been previously analyzed in QVscribe, and that does not include these marks (QVscribe marks may be visible to others that open the document in Excel, even if they do not have QVscribe). In this case, you may remove all marks by pressing Remove Marks on the QVscribe toolbar.

A confirmation window will ask you to confirm that you are about to remove all visible marks from the document. Press OK to confirm, or Cancel to leave the QVscribe marks in the document.

Tip: You can save a copy of your marked requirements documents before removing marks to further speed up any later revisions if needed.

Key/Mouse Actions and Hotkeys for Marking Requirements

Below are Key/Mouse Actions and Hotkeys that can be used in QVscribe for Word.

In Document Actions

Action Type

Result

Double-Click on a single paragraph

Add

Adds selected paragraph as a Requirement.

Double-Click + shift (with a selected requirement)

Modify

Will expand or shrink the Requirement range from the Selected Requirements control range to the paragraph the double-click occurred at.

Double-Click + shift (without a selected requirement)

None

No marking will occur, will just be a word selection highlight.

Double-Click on a Found Requirement

Convert

This will convert the Requirement to a Marked Requirement.

Double Click+ Ctrl on a Marked or Found Requirement

Remove

This will remove the Requirement from the document.

Document + QVscribe Pane Combo Actions

Action Type

Result

Highlight paragraph(s) and click Add button

Add

Adds the paragraph in the highlighted section as a requirement.

Highlight paragraph(s) and click Add button where requirement present in the selected range

None

Nothing will happen and a dialog will appear telling you this.

Select a Marked or Found Requirement and click Remove Button

Remove

This will remove the Requirement from the document.

QVscribe Pane Actions

Action Type

Result

Double-Click on a Found Requirement Node

Convert

This will Convert it to a Marked Requirement

Double-Click +Ctrl on a Marked or Found Requirement Node

Remove

This will remove the Requirement from the document

Double-Click +Ctrl on a selected Group of Marked or Found Requirement Nodes

Remove

This will remove these Requirements from the document

Click on a checked Check Box

Convert

This will convert the Marked Requirement to a Found Requirement

Click on an un-checked Check Box

Convert

This will convert the Found Requirement to a Marked Requirement

Select/highlight Multiple Nodes and click on an unchecked Check Box

Convert

This will convert them all from Found Requirement to a Marked Requirement

Select/highlight Multiple Nodes and click on a checked Check Box

Convert

This will convert them all from Marked Requirement to a Found Requirement

Hit Delete key while selecting a node

Remove

This will remove the Requirement from the document

Up-Down Arrows

Navigation

Will scroll up and down the list in the appropriate direction

Select a Marked or Found Requirement Node and click the Remove button

Remove

This will remove the Requirement from the document

Select/highlight a group of Marked or Found Requirement Nodes and click the Remove button

Remove

This will remove these Requirements from the document

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

Exporting Requirements in QVscribe for Word

After marking requirements in QVscribe for Word, you can export them in CSV format by clicking on Export Requirements on the QVscribe toolbar as shown below.

The CSV file can be generated in either a single column format (denoted as Excel) or in a multi-column format that conforms with the standard IBM Rational DOORs.

Note that you only need to have the requirements marked for the exporting functionality to be
enabled and need not to have analyzed them first. This may be a useful feature for rapidly taking
requirements from Word documents into requirements management tools.

We do suggest running the QVscribe analysis before the exporting function to ensure any issues are
caught before moving into the later stages of development.

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.

QVscribe Toolbar and Pane in QVscribe for Word

Once the QVscribe for Word add-on has been successfully installed and activated, you will see the
QVscribe toolbar as a new tab in the Word 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

  • Toggle Colour Background – Turns on/off the marked requirement highlighting on the document

  • Export Requirements – Prompts to export the marked requirements to CSV formats

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

The QVscribe pane appears on the right-hand side of your Word screen. From the QVscribe pane, you select and navigate requirements, view analysis results, and generate reports.

Note that the QVscribe pane can be undocked and moved to any of the other sides of the Word 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.