HOW THIS GUIDE WORKS

This guide describes how the process of complying with the Rules for Requirement Statements and Sets of Requirements described in the INCOSE Guide for Writing Requirements can be automated and streamlined using QVscribe.

For readers not fully familiar with the INCOSE Guide for Writing Requirements or whose organizations have not sought compliance with its rule set, this guide first presents some background. The next two sections describe the problems associated with the writing of engineering requirements in natural language and typical methods used to try to overcome those problems. Then, the guide introduces the QVscribe analysis tool. Readers who are familiar with the INCOSE rules but unfamiliar with QVscribe may wish to begin with the section titled A Better Way to Write and Review Requirements.

Finally, the guide describes how to automate the process of compliance with the ICOSE rule set. This automation benefits readers and their organization both by speeding up the requirements authoring and review processes and by helping requirements authors write clear and accurate requirements. Readers who are familiar with both the INCOSE rules and QVscribe may want to skip directly to Automating the INCOSE Guide for Writing Requirements with QVscribe.

WRITING CLEAR REQUIREMENTS ISN’T EASY

Most companies understand the need for specifying clear, unambiguous requirements, both for the systems they build and sell, and for the systems they commission and procure from other vendors. Numerous studies have shown that the cost of fixing engineering errors in systems and software increases exponentially over the project life cycle (Jonettei, Boehmii, Rothmaniii, McGibboniv, Chigitalv), and that more than half of all engineering errors originate in the requirements (Martinvi).

Writing clear, unambiguous Natural (spoken) Language requirements on a consistent basis, however, is not easy.

“Natural language’s extensive vocabulary and commonly understood syntax facilitate communication and make it an inviting choice to express requirements,” says William Wilson, a former principal systems engineering consultant with the Software Assurance Technology Center (SATC). “The informality of the language also makes it relatively easy to specify high-level general requirements when precise details are not yet known.

“However, because of differences among formal, colloquial, and popular definitions of words and phrases and the effort required to produce detailed information, these same attributes also contribute to documentation problems. The use of natural language to prescribe complex, dynamic systems has at least three common and severe problems: ambiguity, inaccuracy, and inconsistency.”

A BETTER WAY TO WRITE AND REVIEW REQUIREMENTS

Fortunately, an emerging class of software tools is taking the tedium out of compliance with requirements engineering best practices.

These new tools use advanced natural language processing (NLP) technology to complete in seconds tasks that humans take hours to perform. They automatically analyze individual requirements against known RE best practices and point out requirements that need attention. This automated analysis streamlines the requirement review process and frees domain experts from tedious tasks that don’t require their domain knowledge.

In much the same way that syntax checkers and debuggers help software refine code, these new analysis tools help engineers and analysts refine requirements. They provide a quality assessment of each requirement analyzed, cueing users to possible sources of ambiguity and allowing them to quickly correct problems before sending their requirements for formal review. They’ve been shown to reduce requirement review and correction time by 50 to 75 percent.

QVscribe for Word and Excel

One of these new NLP analysis tools is QVscribe, an add-in for Microsoft Word and Microsoft Excel that analyses the quality and consistency of requirements inside those applications. By integrating with popular authoring tools and presenting its results directly within them, QVscribe helps engineers and analysts reduce ambiguity and improve clarity at the earliest stages of development.

QVscribe automates the tedious steps of the requirement review process. It cues the user to potentially ambiguous requirements and indicates how each may be at odds with accepted best practices. It also provides a risk assessment of each requirement analysed to help users prioritize their review and correction tasks.

Note that QVscribe does not modify any requirements. It only reports where issues exist and why they have been pointed out. It is up to users to validate the tool’s assessments and make any necessary corrections.

QVscribe comes preconfigured with default analysis settings derived from the INCOSE GFWR and NASA requirements engineering standards. The default trigger words and other settings can be assessed and modified as necessary to conform to each project’s specific standards.

THE DRAWBACKS OF ABSTRACT NOTATIONS AND CHECKLISTS

These problems have long been recognized, and systems engineers and have sought solutions to them for years. Until recently, most of these have fallen into two solution classes: (1) elimination of natural language from specifications through use of abstract requirements notations, and (2) use of guides, rule sets and checklists for writing better natural language requirements. Unfortunately, each of these solution classes comes with problems of its own.

Abstract requirement notations come in a wide variety of forms, ranging from semiformal notations like Unified Modelling Language (UML), User Requirements Notation (URN) and other graphical notations, up to formal methods like Z-notation, KAOS and proprietary model-based systems Engineering (MBSE) tools. The main problem with all abstract notations is that they cannot be used throughout the entire systems engineering processes.

In virtually all system development scenarios, abstract methods of requirement expression are inappropriate for many stakeholders. Project stakeholders may come from a wide variety of backgrounds and disciplines and represent a broad spectrum of interests. Those who have nontechnical roles will likely be unfamiliar and uncomfortable with the latest abstract methods. Further, their responsibilities rarely afford them enough time to become conversant in such notations.

As a result, some 95% of engineering specifications use some form of natural language (79% use common natural language, 16% use structured natural language) to express requirements.

To assure requirement quality in these natural language specifications, the most common tool is some sort of guide or checklist. These may be developed internally or by some expert third party. Perhaps the most well-known, respected, and widely used of these third-party requirements quality guides is the Guide for Writing Requirements published by the International Council on Systems Engineering (INCOSE).

Originally published in December 2009 and revised a dozen times since, the INCOSE Guide for Writing Requirements (GFWR) is comprehensive, well-structured and highly readable. It is probably the most complete set of best practices for authoring natural language requirements, and it’s an excellent reference for those seeking to acquire those best practices.

Unfortunately, the same attributes that make the GFWR a great reference also make it and similar rule sets rather unwieldy in the requirements review process. The GFWR’s forty-one rules require more than thirty pages of explanation. Just listing them takes up two pages in the GFWR’s summary sheet. Manually reviewing every requirement in a specification – or even in a change request against an existing specification – against forty-one different rules is an arduous, tedious and time-consuming process.

AUTOMATING THE INCOSE GUIDE FOR WRITING REQUIREMENTS

Coverage of the INCOSE rule set

Figure 1: Rule Coverage Table for the INCOSE Guide for Writing Requirements

INCOSE’s forty-one Rules for Requirement Statements and Sets of Requirements are grouped into fourteen categories. This guide will cover those rules covered by QVscribe’s analyses by category, in the order in which they appear within the GFWR. Rules not automated by QVscribe are not covered in this guide. Some rules—like using proper spelling, grammar and punctuation—are automated by other software tools, like
Microsoft Word. Other rules must be left solely to the expertise of the RE professional.

The Rule Coverage Table (Figure 1) below shows each of the forty-one INCOSE Rules for Requirement Statements and Sets of Requirements. They are grouped according to whether they are addressed by QVscribe, automated by other tools, or left to the RE professional for manual administration.

HOW QVSCRIBE AUTOMATES THE INCOSE RULES FOR REQUIREMENT STATEMENTS

Accuracy Rules

Rule R4: Define Terms

This rule states that terms that have a specific meaning for the project – the names of data variables, for example – should be agreed across the project and defined in a glossary, using a standard which makes glossary terms identifiable in the requirements text. “This is essential for consistency to avoid using the word with its general meaning,” states the GFWR.

Compliance with this rule is largely up to the organization and individuals creating the specification. However, verification that the rule is being applied consistently – across all uses of all defined terms in any given specification – can be greatly accelerated and simplified using QVscribe.

QVscribe’s Term Consistency Analyzer detects all noun phrases present in the marked requirements. It displays those noun phrases along with similar detected terms, and shows which requirements contain them. Users can adjust the degree of similarity to hunt for misspellings and confusion of terms.

Individual terms can be focused on by double-clicking on them in the task pane. Doing so will highlight (in the document pane) all requirements where that term appears, and show (in the task pane) a list of similar terms and the Similarity Percentage for each.

The analyser can also help users compile a glossary of terms used in the document. This practice facilitates consistency in terminology across the project, so users can feel confident everyone involved in the project is speaking the same language.

Accidental exchange of one domain-specific term with another, incorrect spelling of a term or acronym (especially if there are similar domain-specific terms within the document) and use of abbreviations can lead to confusion and errors during implementation. The Term Consistency Analyzer addresses this problem by helping users rapidly verify that similarly spelled terms are all valid, up-to-date, spelled correctly, and used correctly in the requirements where they reside. Consequently, it also helps users comply with Rule R38 (Use terms consistently), Rule R39 (Use acronyms consistently) and Rule R40 (Avoid abbreviations)

Rule R6: Use appropriate units when stating quantities.

As stated in the GFWR, this rule is quite succinct: “All numbers should have units of measure explicitly stated. Temperatures must be stated in terms of the measurement system used.”

Improper or inconsistent use of measurement units can lead to requirement incompatibility and ambiguity.

This makes requirements more difficult to interpret and test and increases the chances of costly design and implementation errors.

QVscribe’s Unit Consistency Analysis displays statistics for the units of magnitude of physical quantities used in the marked requirements.

QVscribe displays all detected units in the Unit Consistency tab of the Analysis Results screen – sorted by type (length, mass, time, etc.) – along with a count of how many times each unit appears in the document.

This feature helps users easily see where different units have been used within the specification, so they can quickly assess compatibility issues (metric vs. imperial, for example), and make needed corrections to ensure all requirements meet project standards.