User Guide. Table of Contents. Version 2.0.9

Transcription

1 User Guide Version Table of Contents 1. Introduction 2 2. Installation and Setup Prerequisites Installing QVscribe for Excel 3 3. Using QVscribe for Excel Accessing and Activating QVscribe The QVscribe Toolbar Activating QVscribe The QVscribe Window Configuring QVscribe Understanding the Configuration Window Adding a New Word/Phrase to the Trigger Words List Editing Word/Phrase in the Trigger Words List Removing Word/Phrase From the Trigger Words List A Note on Continuances and Directives Unit Consistency Exclusion Prefixes Other Settings Selecting Requirements for Analysis Analyzing Requirements The Quality Analysis Sorting and Filtering Results Analysis Details and Term Highlighting The Consistency Analysis The Requirements Similarity Analysis Analysis Reporting Removing all Requirement Marks Getting Support 21 QVscribe for Excel - User Manual v

2 1. Introduction QVscribe for Excel is an Add-In for Microsoft Excel that performs best-practices quality analysis, terminology consistency analysis, unit consistency analysis, and requirement similarity analysis on each individual requirement to help improve the clarity, consistency, and quality of technical requirements. The combined analysis results enable the user to rapidly hone in on problematic requirements and see highlighted within them any inconsistent terminology that could lead to problems down the road. QVscribe has a strong focus on simplicity, usability and integration to provide the most useful analysis information without disrupting or cluttering the user s workflow. This guide will walk you through the general installation and usage of QVscribe for Excel, and describe the user interface and specific features. If you have questions on any of QVscribe features or their usage after reading this guide, please contact us at support@qracorp.com or visit the QRA Help Center at support.qracorp.com. QVscribe for Excel - User Manual v

3 2. Installation and Setup 2.1.Prerequisites The QVscribe for Excel add-in has the following prerequisites for installation: Microsoft Windows version 7, 8.1, or 10 operating system Microsoft Office version 2007, 2010, 2013, or 2016 Visual Studio 2010 Tools for Office Runtime, and Visual C Runtime* *Note: The installer will automatically determine if these Runtime Environments are present in your system and if necessary, it will ask to download and install them prior to the QVscribe installation. 2.2.Installing QVscribe for Excel You will receive a link to download the installation file in your QVscribe order confirmation . If you did not receive the download link, contact us at sales@qracorp.com. The installation file contains the entirety of the QVscribe for Excel add-in. Noting the prerequisites outlined in section 2.1 above, install QVscribe for Excel by following these simple steps: 1. If you had a previous version of QVscribe for Excel installed, it is recommended to first uninstall it with the Add or Remove Programs utility in the Windows Systems Settings. 2. Right-click on the downloaded QVscribeInstaller.exe file. This will first run 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. 3. Once the QVscribe installation wizard finishes, you will need to close and restart Excel to finish the installation. QVscribe for Excel - User Manual v

4 3. Using QVscribe for Excel 3.1.Accessing and Activating QVscribe The QVscribe Toolbar Once the QVscribe for Excel add-on has been successfully installed, and Excel has been restarted, a new QVscribe tab will appear on the Excel toolbar with the following QVscribe buttons.: QVscribe: This button accesses the main QVscribe task pane for requirements detection and analysis. See Sec for more details. Configuration: This button will open the QVscribe Configuration window to access and modify the QVscribe settings. See Sec for more details Activating QVscribe To begin using QVscribe for Excel, click on the QVscribe button in the new QVscribe tab of the toolbar as shown in the image above. The first time you open QVscribe it will display the QVscribe activation screen on the right-hand side of the MS Excel window. Excel Please import your QVscribe for Excel license file to activate the add-in, or if you have not yet obtained a license for QVscribe for Excel, you can begin a 14 day evaluation period by pressing the Start 14 Day Free Evaluation button at the bottom of the activation screen and following the instructions. Once you have successfully entered your license information, the activation screen will switch to the main QVscribe screen and you will now be ready to begin using QVscribe for Excel. QVscribe for Excel - User Manual v

5 3.1.3.The QVscribe Window The QVscribe window appears on the right hand side of the MS-Excel screen. The window can be easily resized by dragging the left hand side edge to the left or to the right. The entire window can be moved and placed on any of the other sides of the Excel window, or undocked and kept as a floating window to maximize the document view while doing revisions. The undocked QVscribe window can also be moved to a second screen if available. In the QVscribe window you are able to select the requirements you want to analyze, navigate analysis results, and generate reports. In the following sections we will explore each of these functions in detail. QVscribe for Excel - User Manual v

6 3.2.Configuring QVscribe QVscribe comes preconfigured with default analysis settings. We always recommend you review and configure the QVscribe settings to adhere to your specific processes and standards. To access the QVscribe Configuration window click on the QVscribe Configuration button in the Home ribbon to invoke the QVscribe Configuration window Understanding the Configuration Window. The QVscribe Configuration window contains five main tabs: Trigger Words, Unit Consistency, Exclusion Prefixes, Settings, and About (see image below). The Trigger Words tab consists of seven subtabs, each representing a class of words/ phrases corresponding to each key quality indicator used in the analysis and scoring of requirements. Table 1 below outlines each of these quality indicators along with corresponding best practices and recommendations. Each quality Indicator sub-tab consists of two lists of trigger words: one list labelled Your Words, which is used by the QVscribe quality analysis; and a list labelled Example Words giving you the set of most common trigger words for you to select as needed. You can move any example word to the Your Words list by selecting it and pressing the arrow below the example 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 standards Adding a New Word/Phrase to the Trigger Words List To add a new word to the Your Words list click the Add button below the list to invoke the Add window. Enter the word/phrase you want to add to the list and then click OK. QVscribe for Excel - User Manual v

7 3.2.3.Editing Word/Phrase in the Trigger Words List To edit an existing trigger word, click on the word you want to edit in the Your Words list and click the Edit button to invoke the Edit window with the current Word/Phrase. Edit the word/phrase as needed and click OK Removing Word/Phrase From the Trigger Words List Click on the trigger word you want to remove from the Your Words list, and click the Remove button. Once all changes to your trigger words 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. However, 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 on the Continuances and/or Directives if these do not meet your approach. QVscribe for Excel - User Manual v

8 Table 1: Description of quality indicators used in the QVscribe analysis. Quality Indicator Description Best practice Recommendation Imperatives Words and phrases that command that something must be done. A proper requirements has exactly one imperative. Ensure an imperative is present in your requirement, or split a requirement with more than one imperative into separate 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, which significantly increases risk. 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. Options Words and phrases that loosen the requirement specification and give latitude in implementation, reducing control and increasing risk. A proper requirement does not use option words or phrases. Restate the requirement with option words as one or more requirements with clear and definite intent. Continuances 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). Although more detail is generally good, too much detail in a single requirement can increase complexity and lead to confusion. It is recommended that requirements with excessive use of continuances are restated as one or more requirements each with simpler specification. Directives Words and phrases pointing to information that aim 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. Some requirements benefit from careful use of directives, however others may be sufficiently concise without the use of directives. Careful use of directives is recommended. Universal Quantifiers Universal Quantifiers are words or phrases that generalize a quantity or quantities relating to a subject. These words should be used carefully and sparingly as they make a requirement difficult or impossible to verify without a thorough understanding of the context. QVscribe will give a warning when it detects a universal quantifier in a requirement, but this will not affect the quality score for the requirement. An option will be given on each requirement to ignore the universal quantifier warning. Unless unavoidable (such as when stating temporal conditions), aim to restate the requirement with specific values for any quantities mentioned. QVscribe for Excel - User Manual v

9 3.2.6.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 userconfigurable 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 units to this list by pressing Add, and entering the details for this new unit 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 that should not be included in the analysis of the actual requirement as they may introduce noise and therefore may skew the requirement's score. To address this the Exclusions Prefixes tab allows you to tell QVscribe of such paragraphs by stating what term(s) is(are) used to define these paragraphs. Note: the paragraph will need to begin with this prefix for QVscribe to relate it to the requirement. QVscribe for Excel - User Manual v

10 3.2.8.Other Settings Requirements background color In the next section you will learn about how QVscribe marks your requirements prior to analysis. Requirement marks can be a useful visual aid to quickly see which requirements QVscribe has detected. The background coloring of these requirement marks can be turned on/off In the Settings tab of the Configuration window. When the Color Marked Requirement Background box is checked, the coloring will always be on, otherwise the mark colouring is only visible when the mouse hoovers over a specific requirement. Importing and exporting your trigger words The trigger word list for each quality indicator are saved as meta-data in each document. This way, opening the document in a different computer with QVscribe for Excel installed will give the same analysis results. You can export the trigger word lists to a file to use them in other documents by pressing the Export Words button in the Settings tab of the QVscribe Configuration window. To retrieve these words at a later time, or to use them with another document, go into the Settings tab again and click on the Import Words button. QVscribe for Excel - User Manual v

11 3.3. Selecting Requirements for Analysis In order for QVscribe to analyze your requirements, you must first add them into the QVscribe environment. This is done by selecting the requirement cell and pressing Add in the Your Requirements list of the QVscribe task pane. You can also select an entire range of cells or an entire column containing requirements and pressing Add. It is also important to define the column containing the requirement ID for these to be preserved with the analyzed requirements, this is easily done on by assigning the column number in the pull down besides the Add button. These added requirements are placed in the Your Requirements list, and are ready to be analyzed. Note that if the Color Marked Requirements Background checkbox is checked in the Settings tab of the QVscribe Configuration window (default setting), then all marked requirements will show in the document with a noticeable background color. This feature is useful specially when zooming out to quickly ensure all requirements have been marked as expected (see side image). Once your requirements are properly marked, they are ready for analysis and for export. QVscribe for Excel - User Manual v

12 3.4.Analyzing Requirements Once you have selected all requirements in the document you will like to analyze, and have ensured that QVscribe has been properly configured (by either pressing Configuration in the QVscribe toolbar, or Customize Your Analysis under the Analysis button), press Analyze # Requirements at the bottom of the main QVscribe task pane, ( # will be the number of confirmed requirements in the document). Note that QVscribe currently has a limit of 3000 requirements per analysis. Once you press Analyze # Requirements you will see the Analysis in progress window. The duration of the analysis process will depend on the number and size of requirements confirmed. In a standard PC this will generally take less than a minute. QVscribe performs three distinct types of analysis on the marked requirements, each focusing on a key area: 1. Requirements Quality: Each requirement is assessed and scored based on established requirements engineering standards and best practices using the following set of Key Quality Indicators: 1 Imperatives Negative Imperatives Options Vagues Continuances Directives Universal Quantifiers These quality indicators are assessed based on the user-configurable trigger words. 2. Term and Unit Consistency: For term consistency, QVscribe detects and highlights all nounphrases found in the requirements and displays them along with the requirements containing them and which other terms are similar to them. This helps verify that domain-specific terminology is consistent throughout the document and that the correct terms are used in each requirement. For unit consistency, QVscribe detects and highlights all units found in the requirements based on a user-configurable units list, and displayed them along with the requirements containing them. This helps assess that all units are consistent throughout the document and that the correct units are used in each requirement. 3. Requirements Similarity: QVscribe analyzes the terminology and structure of each requirement and displays each along with any requirements found to be similar to it. The degree of similarity is adjustable on real time, helping assess if duplicates or contradicting requirements are present. 1 More details on these quality indicators can be found in Table 1 on page 8. QVscribe for Excel - User Manual v

13 3.4.1.The Quality Analysis After the analysis is complete, the main QVscribe window will switch to the results scorecard windows with three tabs: Quality, Consistency, and Similarity. We will first focus on the Quality analysis results tab. This tab show shows a scorecard where each row corresponds to a marked requirement in the document along with its quality score (see image below). At the top of the scorecard an Overall Quality Score The 5-level scoring gives you a succinct picture of which requirements need to the most attention and which ones adhere to best practices. The QVscribe scoring is to be interpreted as follows: A score of one bar ( ) indicates serious errors with the requirement that do not follow established requirements engineering best practices, such as no imperatives in the requirement. 2 A score of 2, 3, or 4 bars ( ) indicates different degrees of problematic terminology, such as vague or optional words, or improper use of continuances and directives. A score of 5 bars ( ) indicates the requirement follows the established best practices based on the configuration of the quality indicators. A warning symbol ( ) indicates that universal quantifiers have been found in the requirement. These do not affect the scoring of the requirement, but bring attention to the domain expert to ensure the actually meant to use a universal quantifier. 2 Refer to Table 1 on page 7 for a description of the quality indicators. QVscribe for Excel - User Manual v

14 Sorting and Filtering Results The value of the scorecard is specially evident when the results are sorted and filtered. This allows for 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 View pulldown list above the Score column and choose from any of the found issues. QVscribe for Excel - User Manual v

15 Analysis Details and Term Highlighting Every requirement in the scorecard that has a score less than 5 bars can be expanded to reveal details on what quality indicators issues led to the given score. When you click and expand a requirement in the analysis window, this also takes you to the requirement within the main document itself and highlights you the source of the problem, helping you assess how to increase the clarity and quality of the requirement. When a specific problem found is selected on the scorecard, the problematic terminology that lead to the given score is highlighted within the requirement itself, helping you understand where exactly the requirement is not meeting best practices. In the image above, an example is shown of a requirement with with its problematic terminology highlighted by QVscribe: The imperative shall appears twice within the same requirement, as well as the vague phrase be able to, and the universal quantifier No. Terminology highlighting is done for all of the quality indicators, the universal quantifiers, the domain specific terminology, and the measurement units. Note: If some analysis results are inconsistent with your company standards, you can reconfigure the quality indicator and units trigger words and settings in the QVscribe Configuration to more directly adhere to your specific practices. QVscribe for Excel - User Manual v

16 3.4.2.The Consistency Analysis The Consistency tab shows the results of the terminology and unit consistency analysis for all analyzed requirements. Incorrect terminology and units in requirements are among the primary culprits of system faults and project delays. QVscribe scans all selected requirements during analysis for terminology and units, and displays these 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 (see image below) Term consistency The term consistency analysis displays all found terms and phrases that appear to be domain specific 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 at the top right side of the tab. 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 (moving the slider to the left), then more terms will be considered similar. The terms in the Consistency tab can also focused on 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 (see figure below). Each of these similar terms can also be expanded to show the requirements where it appears. This helps you rapidly verify that these similar terms are valid in their own right, and reside in the correct requirements. QVscribe for Excel - User Manual v

17 Unit Consistency The Unit Consistency section displays all units detected in the marked requirements along with their type categorization and total count. Each unit on the list can be expanded to show the requirements where it was found. Clicking on any of the requirements in this list under a given unit will bring the focus to the requirement within the document 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 for Excel - User Manual v

18 3.4.3.The Requirements Similarity Analysis The Similarity tab shows the results of the requirement similarity analysis for all requirements confirmed before analysis. Similar to the term similarity function in the Consistency tab, a Matching Strength slider at the top left of the tab lets you adjust how close should the requirements need to be in structure and terminology to be considered similar. Setting the Matching Strength to 100% will only show identical requirement and helps you detect duplicates. Setting the strength to a lesser value will change the tolerance and allow more requirements to be considered similar. It is useful to try different Strength settings as requirements that are very close to each other (say within 75% to 95%) may actually contradict each other, as it could just be a different quantity or possibly a negation of the other requirement. The number of similar requirements found is also 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. QVscribe for Excel - User Manual v

19 3.4.4.Analysis Reporting The final step in using QVscribe for Excel is to generate an analysis report. To do this, press on Generate Report at the bottom of the QVscribe analysis results pane. A window will appear for you to set the location and file name of the analysis report. Once your desired location and filename are set, press Create. The QVscribe analysis report includes: Score Summary Overall Score: 3 Number of Quality Warnings: 21 Document Name: en_uwsu_volume_1_annex_d_appendix_10_compliance_matrix_system_requirem xlsx Date Analyzed: January 5, 2018 at 4:12PM Total Requirements: 141 Document title, analysis date, and total number of analyzed requirements. Score Summary detailing the number of requirements with each score. Score # of Reqs. Percentage What should I do? % Very Low Risk, Move along! 4 1 <1% Low Risk, Check the flow and clarity of the requirement % Medium Risk, Replace negative or amibguous terms with clear and concise ones % High Risk, Focus on what needs to happen and choose clear and unambiguous terminology to re-express the requirement % Very High Risk, Consider what the requirement is trying to convey and rewrite it as one concise requirement, or as separate multiple requirements. Analysis Breakdown Percentage # of Reqs. Color Highlighting No Imperatives 22% 32 No Highlight Vague Words 21% 30 Orange 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. Optional Words 13% 19 Yellow Negative Imperatives 4% 6 Pink Excessive Continuances 3% 5 Lavender Multiple Imperatives <1% 1 Green No Directives N/A N/A No Highlight Individual Requirements Score: Score: The The HMS TAPS USC USC active MF sonar active transmit receive operation beam side-lobes must have should an on-axis not exceed Source -15 Level db relative of no less to the than main $HMS_XMIT_MIN_SL$ lobe for all frequencies db re between 1 Pa at 1 $TAPS_MF_RCV_FMIN_FREQ$ meter, omnidirectional in the horizontal Hz and plane. $TAPS_MF_RCV_FMAX_FREQ$ Hz. Universal Negative Quantifiers Imperatives Vague Words The document to the left gives an example of the general format of the analysis report. Score: 5 Score: 1 Universal Quantifiers The HMS USC active sonar transmit must have a bandwidth of no less than $HMS_XMIT_BANDWIDTH$ Hz The TAPS USC MF active receive sonar operation should continue to operate during active sonar transmissions by either the TAPS USC or the HMS USC. No Imperatives Optional Words Score: 5 Score: 1 Score: No 5 Imperatives Optional Words Vague Words Universal Quantifiers The HMS USC active sonar transmit power settings must perform selection by the operator from full power to -20 db relative to full power In the event of saturation or clipping of the MF active receive array by active sonar transmission, the TAPS USC MF active receive sonar operation should return to normal operation within 25 milliseconds following the end of the transmission The HMS USC active sonar transmit power settings must be selectable by the operator in increments of no greater than 3 db relative to the lowest power setting. Score: 1 Score: 5 No Imperatives The TAPS USC MF active receive capability should have sufficient bandwidth to measure Doppler shifting for targets from The HMS USC active sonar transmit operation must implement the legacy AN/SQS-510 omni-directional, wide-directional, and zero (0) to +/- $MAX_SUB_SPEED$ knots, corrected for ownship relative motion, where $SHIP_TOW_MAX_SPEED$ knots is the narrow-directional transmission modes. maximum ownship towing speed. Optional Words Vague Words Page 1 of 11 QVscribe for Excel - User Manual v

20 3.4.5.Removing all Requirement Marks 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 the Excel document that does not include these marks (since QVscribe marks are visible to others that open the document on MS Excel, even if they do not have QVscribe). In this case you may need to remove all marks by following the steps outlined below. To remove all QVscribe marks from the document, press Remove Marks on the QVscribe section of the MS Excel 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 Excel document. We suggest keeping a marked copy of your requirements documents to further speed up any later revisions. QVscribe for Excel - User Manual v

21 4. Getting Support This guide aims to cover the functionality and processes of all features in QVscribe for Excel. If you have questions that are not addressed in this guide, want to request other features, or want to provide feedback on the tool, please contact us at: You are also welcome to visit the QRA Help Center at support.qracorp.com to find updates and Frequently Asked Questions. QVscribe for Excel - User Manual v